fiftyone.core.odm.document#

Base classes for documents that back dataset contents.

Copyright 2017-2025, Voxel51, Inc.
voxel51.com

Classes:

SerializableDocument()

Mixin for documents that can be serialized in BSON or JSON format.

MongoEngineBaseDocument()

Mixin for all mongoengine:mongoengine.base.BaseDocument subclasses that implements the SerializableDocument interface.

DynamicMixin()

Mixin for MongoEngineBaseDocument classes that can have arbitrary dynamic fields added to them.

BaseDocument()

Base class for documents that are written to the database in their own collections.

DynamicDocument(*args, **values)

Base class for dynamic documents that are stored in a MongoDB collection.

Document(**kwargs)

Base class for documents that are stored in a MongoDB collection.
class fiftyone.core.odm.document.SerializableDocument#

Bases: object

Mixin for documents that can be serialized in BSON or JSON format.

Attributes:

field_names

An ordered tuple of the public fields of this document.

Methods:

fancy_repr([class_name, select_fields, ...])

Generates a customizable string representation of the document.

has_field(field_name)

Determines whether the document has a field of the given name.

get_field(field_name)

Gets the field of the document.

set_field(field_name, value[, create])

Sets the value of a field of the document.

clear_field(field_name)

Clears the field from the document.

iter_fields()

Returns an iterator over the (name, value) pairs of the public fields of the document.

copy()

Returns a deep copy of the document.

merge(doc[, merge_lists, merge_dicts, overwrite])

Merges the contents of the given document into this document.

to_dict([extended])

Serializes this document to a BSON/JSON dictionary.

from_dict(d[, extended])

Loads the document from a BSON/JSON dictionary.

to_json([pretty_print])

Serializes the document to a JSON string.

from_json(s)

Loads the document from a JSON string.
property field_names#

An ordered tuple of the public fields of this document.

fancy_repr(class_name=None, select_fields=None, exclude_fields=None, **kwargs)#

Generates a customizable string representation of the document.

Parameters:

  • class_name (None) – optional class name to use

  • select_fields (None) – iterable of field names to restrict to

  • exclude_fields (None) – iterable of field names to exclude

  • **kwargs – additional key-value pairs to include in the string representation

Returns:

a string representation of the document

has_field(field_name)#

Determines whether the document has a field of the given name.

Parameters:

field_name – the field name

Returns:

True/False

get_field(field_name)#

Gets the field of the document.

Parameters:

field_name – the field name

Returns:

the field value

Raises:

AttributeError – if the field does not exist

set_field(field_name, value, create=True)#

Sets the value of a field of the document.

Parameters:

  • field_name – the field name

  • value – the field value

  • create (True) – whether to create the field if it does not exist

Raises:

ValueError – if field_name is not an allowed field name or does not exist and create == False

clear_field(field_name)#

Clears the field from the document.

Parameters:

field_name – the field name

Raises:

ValueError – if the field does not exist

iter_fields()#

Returns an iterator over the (name, value) pairs of the public fields of the document.

Returns:

an iterator that emits (name, value) tuples

copy()#

Returns a deep copy of the document.

Returns:

a SerializableDocument

merge(doc, merge_lists=True, merge_dicts=True, overwrite=True)#

Merges the contents of the given document into this document.

Parameters:

  • doc – a SerializableDocument of same type as this document

  • merge_lists (True) – whether to merge the elements of top-level list fields rather than treating the list as a single value

  • merge_dicts (True) – whether to recursively merge the contents of top-level dict fields rather than treating the dict as a single value

  • overwrite (True) – whether to overwrite (True) or skip (False) existing fields

to_dict(extended=False)#

Serializes this document to a BSON/JSON dictionary.

Parameters:

extended (False) – whether to serialize extended JSON constructs such as ObjectIDs, Binary, etc. into JSON format

Returns:

a dict

classmethod from_dict(d, extended=False)#

Loads the document from a BSON/JSON dictionary.

Parameters:

  • d – a dictionary

  • extended (False) – whether the input dictionary may contain serialized extended JSON constructs

Returns:

a SerializableDocument

to_json(pretty_print=False)#

Serializes the document to a JSON string.

Parameters:

pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations

Returns:

a JSON string

classmethod from_json(s)#

Loads the document from a JSON string.

Returns:

a SerializableDocument

class fiftyone.core.odm.document.MongoEngineBaseDocument#

Bases: SerializableDocument

Mixin for all mongoengine:mongoengine.base.BaseDocument subclasses that implements the SerializableDocument interface.

Attributes:

field_names

An ordered tuple of the public fields of this document.

Methods:

has_field(field_name)

Determines whether the document has a field of the given name.

get_field(field_name)

Gets the field of the document.

set_field(field_name, value[, create])

Sets the value of a field of the document.

clear_field(field_name)

Clears the field from the document.

field_to_mongo(field_name)

field_to_python(field_name, value)

to_dict([extended])

Serializes this document to a BSON/JSON dictionary.

from_dict(d[, extended])

Loads the document from a BSON/JSON dictionary.

copy()

Returns a deep copy of the document.

fancy_repr([class_name, select_fields, ...])

Generates a customizable string representation of the document.

from_json(s)

Loads the document from a JSON string.

iter_fields()

Returns an iterator over the (name, value) pairs of the public fields of the document.

merge(doc[, merge_lists, merge_dicts, overwrite])

Merges the contents of the given document into this document.

to_json([pretty_print])

Serializes the document to a JSON string.
property field_names#

An ordered tuple of the public fields of this document.

has_field(field_name)#

Determines whether the document has a field of the given name.

Parameters:

field_name – the field name

Returns:

True/False

get_field(field_name)#

Gets the field of the document.

Parameters:

field_name – the field name

Returns:

the field value

Raises:

AttributeError – if the field does not exist

set_field(field_name, value, create=True)#

Sets the value of a field of the document.

Parameters:

  • field_name – the field name

  • value – the field value

  • create (True) – whether to create the field if it does not exist

Raises:

ValueError – if field_name is not an allowed field name or does not exist and create == False

clear_field(field_name)#

Clears the field from the document.

Parameters:

field_name – the field name

Raises:

ValueError – if the field does not exist

field_to_mongo(field_name)#
field_to_python(field_name, value)#
to_dict(extended=False)#

Serializes this document to a BSON/JSON dictionary.

Parameters:

extended (False) – whether to serialize extended JSON constructs such as ObjectIDs, Binary, etc. into JSON format

Returns:

a dict

classmethod from_dict(d, extended=False)#

Loads the document from a BSON/JSON dictionary.

Parameters:

  • d – a dictionary

  • extended (False) – whether the input dictionary may contain serialized extended JSON constructs

Returns:

a SerializableDocument

copy()#

Returns a deep copy of the document.

Returns:

a SerializableDocument

fancy_repr(class_name=None, select_fields=None, exclude_fields=None, **kwargs)#

Generates a customizable string representation of the document.

Parameters:

  • class_name (None) – optional class name to use

  • select_fields (None) – iterable of field names to restrict to

  • exclude_fields (None) – iterable of field names to exclude

  • **kwargs – additional key-value pairs to include in the string representation

Returns:

a string representation of the document

classmethod from_json(s)#

Loads the document from a JSON string.

Returns:

a SerializableDocument

iter_fields()#

Returns an iterator over the (name, value) pairs of the public fields of the document.

Returns:

an iterator that emits (name, value) tuples

merge(doc, merge_lists=True, merge_dicts=True, overwrite=True)#

Merges the contents of the given document into this document.

Parameters:

  • doc – a SerializableDocument of same type as this document

  • merge_lists (True) – whether to merge the elements of top-level list fields rather than treating the list as a single value

  • merge_dicts (True) – whether to recursively merge the contents of top-level dict fields rather than treating the dict as a single value

  • overwrite (True) – whether to overwrite (True) or skip (False) existing fields

to_json(pretty_print=False)#

Serializes the document to a JSON string.

Parameters:

pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations

Returns:

a JSON string

class fiftyone.core.odm.document.DynamicMixin#

Bases: object

Mixin for MongoEngineBaseDocument classes that can have arbitrary dynamic fields added to them.

Methods:

to_mongo(*args, **kwargs)

to_mongo(*args, **kwargs)#
class fiftyone.core.odm.document.BaseDocument#

Bases: MongoEngineBaseDocument

Base class for documents that are written to the database in their own collections.

The ID of a document is automatically populated when it is added to the database, and the ID of a document is None if it has not been added to the database.

id#

the ID of the document, or None if it has not been added to the database

Attributes:

in_db

Whether the document has been inserted into the database.

field_names

An ordered tuple of the public fields of this document.

Methods:

clear_field(field_name)

Clears the field from the document.

copy()

Returns a deep copy of the document.

fancy_repr([class_name, select_fields, ...])

Generates a customizable string representation of the document.

field_to_mongo(field_name)

field_to_python(field_name, value)

from_dict(d[, extended])

Loads the document from a BSON/JSON dictionary.

from_json(s)

Loads the document from a JSON string.

get_field(field_name)

Gets the field of the document.

has_field(field_name)

Determines whether the document has a field of the given name.

iter_fields()

Returns an iterator over the (name, value) pairs of the public fields of the document.

merge(doc[, merge_lists, merge_dicts, overwrite])

Merges the contents of the given document into this document.

set_field(field_name, value[, create])

Sets the value of a field of the document.

to_dict([extended])

Serializes this document to a BSON/JSON dictionary.

to_json([pretty_print])

Serializes the document to a JSON string.
property in_db#

Whether the document has been inserted into the database.

clear_field(field_name)#

Clears the field from the document.

Parameters:

field_name – the field name

Raises:

ValueError – if the field does not exist

copy()#

Returns a deep copy of the document.

Returns:

a SerializableDocument

fancy_repr(class_name=None, select_fields=None, exclude_fields=None, **kwargs)#

Generates a customizable string representation of the document.

Parameters:

  • class_name (None) – optional class name to use

  • select_fields (None) – iterable of field names to restrict to

  • exclude_fields (None) – iterable of field names to exclude

  • **kwargs – additional key-value pairs to include in the string representation

Returns:

a string representation of the document

property field_names#

An ordered tuple of the public fields of this document.

field_to_mongo(field_name)#
field_to_python(field_name, value)#
classmethod from_dict(d, extended=False)#

Loads the document from a BSON/JSON dictionary.

Parameters:

  • d – a dictionary

  • extended (False) – whether the input dictionary may contain serialized extended JSON constructs

Returns:

a SerializableDocument

classmethod from_json(s)#

Loads the document from a JSON string.

Returns:

a SerializableDocument

get_field(field_name)#

Gets the field of the document.

Parameters:

field_name – the field name

Returns:

the field value

Raises:

AttributeError – if the field does not exist

has_field(field_name)#

Determines whether the document has a field of the given name.

Parameters:

field_name – the field name

Returns:

True/False

iter_fields()#

Returns an iterator over the (name, value) pairs of the public fields of the document.

Returns:

an iterator that emits (name, value) tuples

merge(doc, merge_lists=True, merge_dicts=True, overwrite=True)#

Merges the contents of the given document into this document.

Parameters:

  • doc – a SerializableDocument of same type as this document

  • merge_lists (True) – whether to merge the elements of top-level list fields rather than treating the list as a single value

  • merge_dicts (True) – whether to recursively merge the contents of top-level dict fields rather than treating the dict as a single value

  • overwrite (True) – whether to overwrite (True) or skip (False) existing fields

set_field(field_name, value, create=True)#

Sets the value of a field of the document.

Parameters:

  • field_name – the field name

  • value – the field value

  • create (True) – whether to create the field if it does not exist

Raises:

ValueError – if field_name is not an allowed field name or does not exist and create == False

to_dict(extended=False)#

Serializes this document to a BSON/JSON dictionary.

Parameters:

extended (False) – whether to serialize extended JSON constructs such as ObjectIDs, Binary, etc. into JSON format

Returns:

a dict

to_json(pretty_print=False)#

Serializes the document to a JSON string.

Parameters:

pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations

Returns:

a JSON string

class fiftyone.core.odm.document.DynamicDocument(*args, **values)#

Bases: DynamicMixin, BaseDocument, DynamicDocument

Base class for dynamic documents that are stored in a MongoDB collection.

Dynamic documents can have arbitrary fields added to them.

The ID of a document is automatically populated when it is added to the database, and the ID of a document is None if it has not been added to the database.

id#

the ID of the document, or None if it has not been added to the database

Attributes:

STRICT

field_names

An ordered tuple of the public fields of this document.

in_db

Whether the document has been inserted into the database.

pk

Get the primary key.

Methods:

cascade_save(**kwargs)

Recursively save any references and generic references on the document.

clean()

Hook for doing document level data cleaning (usually validation or assignment) before validation is run.

clear_field(field_name)

Clears the field from the document.

compare_indexes()

Compares the indexes defined in MongoEngine with the ones existing in the database.

copy()

Returns a deep copy of the document.

create_index(keys[, background])

Creates the given indexes if required.

delete([signal_kwargs])

Delete the Document from the database.

drop_collection()

Drops the entire collection associated with this Document type from the database.

ensure_indexes()

Checks the document meta data and ensures all the indexes exist.

fancy_repr([class_name, select_fields, ...])

Generates a customizable string representation of the document.

field_to_mongo(field_name)

field_to_python(field_name, value)

from_dict(d[, extended])

Loads the document from a BSON/JSON dictionary.

from_json(s)

Loads the document from a JSON string.

get_field(field_name)

Gets the field of the document.

get_text_score()

Get text score from text query

has_field(field_name)

Determines whether the document has a field of the given name.

iter_fields()

Returns an iterator over the (name, value) pairs of the public fields of the document.

list_indexes()

Lists all indexes that should be created for the Document collection.

merge(doc[, merge_lists, merge_dicts, overwrite])

Merges the contents of the given document into this document.

modify([query])

Perform an atomic update of the document in the database and reload the document object using updated version.

register_delete_rule(document_cls, ...)

This method registers the delete rules to apply when removing this object.

reload(*fields, **kwargs)

Reloads all attributes from the database.

save([force_insert, validate, clean, ...])

Save the Document to the database.

select_related([max_depth])

Handles dereferencing of DBRef objects to a maximum depth in order to cut down the number queries to mongodb.

set_field(field_name, value[, create])

Sets the value of a field of the document.

switch_collection(collection_name[, ...])

Temporarily switch the collection for a document instance.

switch_db(db_alias[, keep_created])

Temporarily switch the database for a document instance.

to_dbref()

Returns an instance of DBRef useful in __raw__ queries.

to_dict([extended])

Serializes this document to a BSON/JSON dictionary.

to_json([pretty_print])

Serializes the document to a JSON string.

to_mongo(*args, **kwargs)

Return as SON data ready for use with MongoDB.

update(**kwargs)

Performs an update on the Document A convenience wrapper to update().

validate([clean])

Ensure that all fields' values are valid and that required fields are present.

Classes:

my_metaclass

alias of TopLevelDocumentMetaclass
STRICT = False#
cascade_save(**kwargs)#

Recursively save any references and generic references on the document.

clean()#

Hook for doing document level data cleaning (usually validation or assignment) before validation is run.

Any ValidationError raised by this method will not be associated with a particular field; it will have a special-case association with the field defined by NON_FIELD_ERRORS.

clear_field(field_name)#

Clears the field from the document.

Parameters:

field_name – the field name

Raises:

ValueError – if the field does not exist

classmethod compare_indexes()#

Compares the indexes defined in MongoEngine with the ones existing in the database. Returns any missing/extra indexes.

copy()#

Returns a deep copy of the document.

Returns:

a SerializableDocument

classmethod create_index(keys, background=False, **kwargs)#

Creates the given indexes if required.

Parameters:

  • keys – a single index key or a list of index keys (to construct a multi-field index); keys may be prefixed with a + or a - to determine the index ordering

  • background – Allows index creation in the background

delete(signal_kwargs=None, **write_concern)#

Delete the Document from the database. This will only take effect if the document has been previously saved.

Parameters:

  • signal_kwargs – (optional) kwargs dictionary to be passed to the signal calls.

  • write_concern – Extra keyword arguments are passed down which will be used as options for the resultant getLastError command. For example, save(..., w: 2, fsync: True) will wait until at least two servers have recorded the write and will force an fsync on the primary server.

classmethod drop_collection()#

Drops the entire collection associated with this Document type from the database.

Raises OperationError if the document has no collection set (i.g. if it is abstract)

classmethod ensure_indexes()#

Checks the document meta data and ensures all the indexes exist.

Global defaults can be set in the meta - see guide/defining-documents

By default, this will get called automatically upon first interaction with the Document collection (query, save, etc) so unless you disabled auto_create_index, you shouldn’t have to call this manually.

This also gets called upon every call to Document.save if auto_create_index_on_save is set to True

If called multiple times, MongoDB will not re-recreate indexes if they exist already

Note

You can disable automatic index creation by setting auto_create_index to False in the documents meta data

fancy_repr(class_name=None, select_fields=None, exclude_fields=None, **kwargs)#

Generates a customizable string representation of the document.

Parameters:

  • class_name (None) – optional class name to use

  • select_fields (None) – iterable of field names to restrict to

  • exclude_fields (None) – iterable of field names to exclude

  • **kwargs – additional key-value pairs to include in the string representation

Returns:

a string representation of the document

property field_names#

An ordered tuple of the public fields of this document.

field_to_mongo(field_name)#
field_to_python(field_name, value)#
classmethod from_dict(d, extended=False)#

Loads the document from a BSON/JSON dictionary.

Parameters:

  • d – a dictionary

  • extended (False) – whether the input dictionary may contain serialized extended JSON constructs

Returns:

a SerializableDocument

classmethod from_json(s)#

Loads the document from a JSON string.

Returns:

a SerializableDocument

get_field(field_name)#

Gets the field of the document.

Parameters:

field_name – the field name

Returns:

the field value

Raises:

AttributeError – if the field does not exist

get_text_score()#

Get text score from text query

has_field(field_name)#

Determines whether the document has a field of the given name.

Parameters:

field_name – the field name

Returns:

True/False

property in_db#

Whether the document has been inserted into the database.

iter_fields()#

Returns an iterator over the (name, value) pairs of the public fields of the document.

Returns:

an iterator that emits (name, value) tuples

classmethod list_indexes()#

Lists all indexes that should be created for the Document collection. It includes all the indexes from super- and sub-classes.

Note that it will only return the indexes’ fields, not the indexes’ options

merge(doc, merge_lists=True, merge_dicts=True, overwrite=True)#

Merges the contents of the given document into this document.

Parameters:

  • doc – a SerializableDocument of same type as this document

  • merge_lists (True) – whether to merge the elements of top-level list fields rather than treating the list as a single value

  • merge_dicts (True) – whether to recursively merge the contents of top-level dict fields rather than treating the dict as a single value

  • overwrite (True) – whether to overwrite (True) or skip (False) existing fields

modify(query=None, **update)#

Perform an atomic update of the document in the database and reload the document object using updated version.

Returns True if the document has been updated or False if the document in the database doesn’t match the query.

Note

All unsaved changes that have been made to the document are rejected if the method returns True.

Parameters:

  • query – the update will be performed only if the document in the database matches the query

  • update – Django-style update keyword arguments

my_metaclass#

alias of TopLevelDocumentMetaclass

property pk#

Get the primary key.

classmethod register_delete_rule(document_cls, field_name, rule)#

This method registers the delete rules to apply when removing this object.

reload(*fields, **kwargs)#

Reloads all attributes from the database.

Parameters:

  • fields – (optional) args list of fields to reload

  • max_depth – (optional) depth of dereferencing to follow

save(force_insert=False, validate=True, clean=True, write_concern=None, cascade=None, cascade_kwargs=None, _refs=None, save_condition=None, signal_kwargs=None, **kwargs)#

Save the Document to the database. If the document already exists, it will be updated, otherwise it will be created. Returns the saved object instance.

Parameters:

  • force_insert – only try to create a new document, don’t allow updates of existing documents.

  • validate – validates the document; set to False to skip.

  • clean – call the document clean method, requires validate to be True.

  • write_concern – Extra keyword arguments are passed down to save() OR insert() which will be used as options for the resultant getLastError command. For example, save(..., write_concern={w: 2, fsync: True}, ...) will wait until at least two servers have recorded the write and will force an fsync on the primary server.

  • cascade – Sets the flag for cascading saves. You can set a default by setting “cascade” in the document __meta__

  • cascade_kwargs – (optional) kwargs dictionary to be passed throw to cascading saves. Implies cascade=True.

  • _refs – A list of processed references used in cascading saves

  • save_condition – only perform save if matching record in db satisfies condition(s) (e.g. version number). Raises OperationError if the conditions are not satisfied

  • signal_kwargs – (optional) kwargs dictionary to be passed to the signal calls.

Changed in version 0.5: In existing documents it only saves changed fields using set / unset. Saves are cascaded and any DBRef objects that have changes are saved as well.

Changed in version 0.6: Added cascading saves

Changed in version 0.8: Cascade saves are optional and default to False. If you want fine grain control then you can turn off using document meta[‘cascade’] = True. Also you can pass different kwargs to the cascade save using cascade_kwargs which overwrites the existing kwargs with custom values.

Changed in version 0.26: save() no longer calls ensure_indexes() unless meta['auto_create_index_on_save'] is set to True.

Handles dereferencing of DBRef objects to a maximum depth in order to cut down the number queries to mongodb.

set_field(field_name, value, create=True)#

Sets the value of a field of the document.

Parameters:

  • field_name – the field name

  • value – the field value

  • create (True) – whether to create the field if it does not exist

Raises:

ValueError – if field_name is not an allowed field name or does not exist and create == False

switch_collection(collection_name, keep_created=True)#

Temporarily switch the collection for a document instance.

Only really useful for archiving off data and calling save():

user = User.objects.get(id=user_id)
user.switch_collection('old-users')
user.save()
Parameters:

  • collection_name (str) – The database alias to use for saving the document

  • keep_created (bool) – keep self._created value after switching collection, else is reset to True

See also

Use switch_db if you need to read from another database

switch_db(db_alias, keep_created=True)#

Temporarily switch the database for a document instance.

Only really useful for archiving off data and calling save():

user = User.objects.get(id=user_id)
user.switch_db('archive-db')
user.save()
Parameters:

  • db_alias (str) – The database alias to use for saving the document

  • keep_created (bool) – keep self._created value after switching db, else is reset to True

See also

Use switch_collection if you need to read from another collection

to_dbref()#

Returns an instance of DBRef useful in __raw__ queries.

to_dict(extended=False)#

Serializes this document to a BSON/JSON dictionary.

Parameters:

extended (False) – whether to serialize extended JSON constructs such as ObjectIDs, Binary, etc. into JSON format

Returns:

a dict

to_json(pretty_print=False)#

Serializes the document to a JSON string.

Parameters:

pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations

Returns:

a JSON string

to_mongo(*args, **kwargs)#

Return as SON data ready for use with MongoDB.

update(**kwargs)#

Performs an update on the Document A convenience wrapper to update().

Raises OperationError if called on an object that has not yet been saved.

validate(clean=True)#

Ensure that all fields’ values are valid and that required fields are present.

Raises ValidationError if any of the fields’ values are found to be invalid.

class fiftyone.core.odm.document.Document(**kwargs)#

Bases: BaseDocument, Document

Base class for documents that are stored in a MongoDB collection.

The ID of a document is automatically populated when it is added to the database, and the ID of a document is None if it has not been added to the database.

id#

the ID of the document, or None if it has not been added to the database

Methods:

copy([new_id])

Returns a deep copy of the document.

reload(*fields, **kwargs)

Reloads the document from the database.

save([upsert, validate, safe])

Saves the document to the database.

copy_with_new_id()

cascade_save(**kwargs)

Recursively save any references and generic references on the document.

clean()

Hook for doing document level data cleaning (usually validation or assignment) before validation is run.

clear_field(field_name)

Clears the field from the document.

compare_indexes()

Compares the indexes defined in MongoEngine with the ones existing in the database.

create_index(keys[, background])

Creates the given indexes if required.

delete([signal_kwargs])

Delete the Document from the database.

drop_collection()

Drops the entire collection associated with this Document type from the database.

ensure_indexes()

Checks the document meta data and ensures all the indexes exist.

fancy_repr([class_name, select_fields, ...])

Generates a customizable string representation of the document.

field_to_mongo(field_name)

field_to_python(field_name, value)

from_dict(d[, extended])

Loads the document from a BSON/JSON dictionary.

from_json(s)

Loads the document from a JSON string.

get_field(field_name)

Gets the field of the document.

get_text_score()

Get text score from text query

has_field(field_name)

Determines whether the document has a field of the given name.

iter_fields()

Returns an iterator over the (name, value) pairs of the public fields of the document.

list_indexes()

Lists all indexes that should be created for the Document collection.

merge(doc[, merge_lists, merge_dicts, overwrite])

Merges the contents of the given document into this document.

modify([query])

Perform an atomic update of the document in the database and reload the document object using updated version.

register_delete_rule(document_cls, ...)

This method registers the delete rules to apply when removing this object.

select_related([max_depth])

Handles dereferencing of DBRef objects to a maximum depth in order to cut down the number queries to mongodb.

set_field(field_name, value[, create])

Sets the value of a field of the document.

switch_collection(collection_name[, ...])

Temporarily switch the collection for a document instance.

switch_db(db_alias[, keep_created])

Temporarily switch the database for a document instance.

to_dbref()

Returns an instance of DBRef useful in __raw__ queries.

to_dict([extended])

Serializes this document to a BSON/JSON dictionary.

to_json([pretty_print])

Serializes the document to a JSON string.

to_mongo(*args, **kwargs)

Return as SON data ready for use with MongoDB.

update(**kwargs)

Performs an update on the Document A convenience wrapper to update().

validate([clean])

Ensure that all fields' values are valid and that required fields are present.

Attributes:

STRICT

field_names

An ordered tuple of the public fields of this document.

in_db

Whether the document has been inserted into the database.

pk

Get the primary key.

Classes:

my_metaclass

alias of TopLevelDocumentMetaclass
copy(new_id=False)#

Returns a deep copy of the document.

Parameters:

new_id (False) – whether to generate a new ID for the copied document. By default, the ID is left as None and will be automatically populated when the document is added to the database

reload(*fields, **kwargs)#

Reloads the document from the database.

Parameters:

*fields – an optional args list of specific fields to reload

save(upsert=False, validate=True, safe=False, **kwargs)#

Saves the document to the database.

If the document already exists, it will be updated, otherwise it will be created.

Parameters:

  • upsert (False) – whether to insert the document if it has an id populated but no document with that ID exists in the database

  • validate (True) – whether to validate the document

  • safe (False) – whether to reload() the document before raising any errors

Returns:

self

copy_with_new_id()#
STRICT = False#
cascade_save(**kwargs)#

Recursively save any references and generic references on the document.

clean()#

Hook for doing document level data cleaning (usually validation or assignment) before validation is run.

Any ValidationError raised by this method will not be associated with a particular field; it will have a special-case association with the field defined by NON_FIELD_ERRORS.

clear_field(field_name)#

Clears the field from the document.

Parameters:

field_name – the field name

Raises:

ValueError – if the field does not exist

classmethod compare_indexes()#

Compares the indexes defined in MongoEngine with the ones existing in the database. Returns any missing/extra indexes.

classmethod create_index(keys, background=False, **kwargs)#

Creates the given indexes if required.

Parameters:

  • keys – a single index key or a list of index keys (to construct a multi-field index); keys may be prefixed with a + or a - to determine the index ordering

  • background – Allows index creation in the background

delete(signal_kwargs=None, **write_concern)#

Delete the Document from the database. This will only take effect if the document has been previously saved.

Parameters:

  • signal_kwargs – (optional) kwargs dictionary to be passed to the signal calls.

  • write_concern – Extra keyword arguments are passed down which will be used as options for the resultant getLastError command. For example, save(..., w: 2, fsync: True) will wait until at least two servers have recorded the write and will force an fsync on the primary server.

classmethod drop_collection()#

Drops the entire collection associated with this Document type from the database.

Raises OperationError if the document has no collection set (i.g. if it is abstract)

classmethod ensure_indexes()#

Checks the document meta data and ensures all the indexes exist.

Global defaults can be set in the meta - see guide/defining-documents

By default, this will get called automatically upon first interaction with the Document collection (query, save, etc) so unless you disabled auto_create_index, you shouldn’t have to call this manually.

This also gets called upon every call to Document.save if auto_create_index_on_save is set to True

If called multiple times, MongoDB will not re-recreate indexes if they exist already

Note

You can disable automatic index creation by setting auto_create_index to False in the documents meta data

fancy_repr(class_name=None, select_fields=None, exclude_fields=None, **kwargs)#

Generates a customizable string representation of the document.

Parameters:

  • class_name (None) – optional class name to use

  • select_fields (None) – iterable of field names to restrict to

  • exclude_fields (None) – iterable of field names to exclude

  • **kwargs – additional key-value pairs to include in the string representation

Returns:

a string representation of the document

property field_names#

An ordered tuple of the public fields of this document.

field_to_mongo(field_name)#
field_to_python(field_name, value)#
classmethod from_dict(d, extended=False)#

Loads the document from a BSON/JSON dictionary.

Parameters:

  • d – a dictionary

  • extended (False) – whether the input dictionary may contain serialized extended JSON constructs

Returns:

a SerializableDocument

classmethod from_json(s)#

Loads the document from a JSON string.

Returns:

a SerializableDocument

get_field(field_name)#

Gets the field of the document.

Parameters:

field_name – the field name

Returns:

the field value

Raises:

AttributeError – if the field does not exist

get_text_score()#

Get text score from text query

has_field(field_name)#

Determines whether the document has a field of the given name.

Parameters:

field_name – the field name

Returns:

True/False

property in_db#

Whether the document has been inserted into the database.

iter_fields()#

Returns an iterator over the (name, value) pairs of the public fields of the document.

Returns:

an iterator that emits (name, value) tuples

classmethod list_indexes()#

Lists all indexes that should be created for the Document collection. It includes all the indexes from super- and sub-classes.

Note that it will only return the indexes’ fields, not the indexes’ options

merge(doc, merge_lists=True, merge_dicts=True, overwrite=True)#

Merges the contents of the given document into this document.

Parameters:

  • doc – a SerializableDocument of same type as this document

  • merge_lists (True) – whether to merge the elements of top-level list fields rather than treating the list as a single value

  • merge_dicts (True) – whether to recursively merge the contents of top-level dict fields rather than treating the dict as a single value

  • overwrite (True) – whether to overwrite (True) or skip (False) existing fields

modify(query=None, **update)#

Perform an atomic update of the document in the database and reload the document object using updated version.

Returns True if the document has been updated or False if the document in the database doesn’t match the query.

Note

All unsaved changes that have been made to the document are rejected if the method returns True.

Parameters:

  • query – the update will be performed only if the document in the database matches the query

  • update – Django-style update keyword arguments

my_metaclass#

alias of TopLevelDocumentMetaclass

property pk#

Get the primary key.

classmethod register_delete_rule(document_cls, field_name, rule)#

This method registers the delete rules to apply when removing this object.

Handles dereferencing of DBRef objects to a maximum depth in order to cut down the number queries to mongodb.

set_field(field_name, value, create=True)#

Sets the value of a field of the document.

Parameters:

  • field_name – the field name

  • value – the field value

  • create (True) – whether to create the field if it does not exist

Raises:

ValueError – if field_name is not an allowed field name or does not exist and create == False

switch_collection(collection_name, keep_created=True)#

Temporarily switch the collection for a document instance.

Only really useful for archiving off data and calling save():

user = User.objects.get(id=user_id)
user.switch_collection('old-users')
user.save()
Parameters:

  • collection_name (str) – The database alias to use for saving the document

  • keep_created (bool) – keep self._created value after switching collection, else is reset to True

See also

Use switch_db if you need to read from another database

switch_db(db_alias, keep_created=True)#

Temporarily switch the database for a document instance.

Only really useful for archiving off data and calling save():

user = User.objects.get(id=user_id)
user.switch_db('archive-db')
user.save()
Parameters:

  • db_alias (str) – The database alias to use for saving the document

  • keep_created (bool) – keep self._created value after switching db, else is reset to True

See also

Use switch_collection if you need to read from another collection

to_dbref()#

Returns an instance of DBRef useful in __raw__ queries.

to_dict(extended=False)#

Serializes this document to a BSON/JSON dictionary.

Parameters:

extended (False) – whether to serialize extended JSON constructs such as ObjectIDs, Binary, etc. into JSON format

Returns:

a dict

to_json(pretty_print=False)#

Serializes the document to a JSON string.

Parameters:

pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations

Returns:

a JSON string

to_mongo(*args, **kwargs)#

Return as SON data ready for use with MongoDB.

update(**kwargs)#

Performs an update on the Document A convenience wrapper to update().

Raises OperationError if called on an object that has not yet been saved.

validate(clean=True)#

Ensure that all fields’ values are valid and that required fields are present.

Raises ValidationError if any of the fields’ values are found to be invalid.

IN THIS ARTICLE