# fiftyone.core.odm.embedded_document Base classes for documents that back dataset contents. Copyright 2017-2026, Voxel51, Inc.
[voxel51.com](https://voxel51.com/)

**Classes:** | [`BaseEmbeddedDocument`](#fiftyone.core.odm.embedded_document.BaseEmbeddedDocument)() | Base class for documents that are embedded within other documents and therefore are not stored in their own collection in the database. | |---------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------| | [`EmbeddedDocument`](#fiftyone.core.odm.embedded_document.EmbeddedDocument)(\*args, \*\*kwargs) | Base class for documents that are embedded within other documents and therefore are not stored in their own collection in the database. | | [`DynamicEmbeddedDocument`](#fiftyone.core.odm.embedded_document.DynamicEmbeddedDocument)(\*args, \*\*kwargs) | Base class for dynamic documents that are embedded within other documents and therefore aren't stored in their own collection in the database. | **Exceptions:** | [`DynamicEmbeddedDocumentException`](#fiftyone.core.odm.embedded_document.DynamicEmbeddedDocumentException) | Exception raised when an error occurs in a dynamic document operation. | |---------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------| ### *class* fiftyone.core.odm.embedded_document.BaseEmbeddedDocument Bases: [`MongoEngineBaseDocument`](fiftyone.core.odm.document.md#fiftyone.core.odm.document.MongoEngineBaseDocument) Base class for documents that are embedded within other documents and therefore are not stored in their own collection in the database. **Methods:** | [`clear_field`](#fiftyone.core.odm.embedded_document.BaseEmbeddedDocument.clear_field)(field_name) | Clears the field from the document. | |------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------| | [`copy`](#fiftyone.core.odm.embedded_document.BaseEmbeddedDocument.copy)() | Returns a deep copy of the document. | | [`fancy_repr`](#fiftyone.core.odm.embedded_document.BaseEmbeddedDocument.fancy_repr)([class_name, select_fields, ...]) | Generates a customizable string representation of the document. | | [`field_to_mongo`](#fiftyone.core.odm.embedded_document.BaseEmbeddedDocument.field_to_mongo)(field_name) | | | [`field_to_python`](#fiftyone.core.odm.embedded_document.BaseEmbeddedDocument.field_to_python)(field_name, value) | | | [`from_dict`](#fiftyone.core.odm.embedded_document.BaseEmbeddedDocument.from_dict)(d[, extended]) | Loads the document from a BSON/JSON dictionary. | | [`from_json`](#fiftyone.core.odm.embedded_document.BaseEmbeddedDocument.from_json)(s) | Loads the document from a JSON string. | | [`get_field`](#fiftyone.core.odm.embedded_document.BaseEmbeddedDocument.get_field)(field_name) | Gets the field of the document. | | [`has_field`](#fiftyone.core.odm.embedded_document.BaseEmbeddedDocument.has_field)(field_name) | Determines whether the document has a field of the given name. | | [`iter_fields`](#fiftyone.core.odm.embedded_document.BaseEmbeddedDocument.iter_fields)() | Returns an iterator over the `(name, value)` pairs of the public fields of the document. | | [`merge`](#fiftyone.core.odm.embedded_document.BaseEmbeddedDocument.merge)(doc[, merge_lists, merge_dicts, overwrite]) | Merges the contents of the given document into this document. | | [`set_field`](#fiftyone.core.odm.embedded_document.BaseEmbeddedDocument.set_field)(field_name, value[, create]) | Sets the value of a field of the document. | | [`to_dict`](#fiftyone.core.odm.embedded_document.BaseEmbeddedDocument.to_dict)([extended]) | Serializes this document to a BSON/JSON dictionary. | | [`to_json`](#fiftyone.core.odm.embedded_document.BaseEmbeddedDocument.to_json)([pretty_print]) | Serializes the document to a JSON string. | **Attributes:** | [`field_names`](#fiftyone.core.odm.embedded_document.BaseEmbeddedDocument.field_names) | An ordered tuple of the public fields of this document. | |------------------------------------------------------------------------------------------|-----------------------------------------------------------| #### 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.embedded_document.EmbeddedDocument(\*args, \*\*kwargs) Bases: [`BaseEmbeddedDocument`](#fiftyone.core.odm.embedded_document.BaseEmbeddedDocument), `EmbeddedDocument` Base class for documents that are embedded within other documents and therefore are not stored in their own collection in the database. **Attributes:** | [`STRICT`](#fiftyone.core.odm.embedded_document.EmbeddedDocument.STRICT) | | |------------------------------------------------------------------------------------|---------------------------------------------------------| | [`field_names`](#fiftyone.core.odm.embedded_document.EmbeddedDocument.field_names) | An ordered tuple of the public fields of this document. | **Methods:** | [`clean`](#fiftyone.core.odm.embedded_document.EmbeddedDocument.clean)() | Hook for doing document level data cleaning (usually validation or assignment) before validation is run. | |--------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------| | [`clear_field`](#fiftyone.core.odm.embedded_document.EmbeddedDocument.clear_field)(field_name) | Clears the field from the document. | | [`copy`](#fiftyone.core.odm.embedded_document.EmbeddedDocument.copy)() | Returns a deep copy of the document. | | [`fancy_repr`](#fiftyone.core.odm.embedded_document.EmbeddedDocument.fancy_repr)([class_name, select_fields, ...]) | Generates a customizable string representation of the document. | | [`field_to_mongo`](#fiftyone.core.odm.embedded_document.EmbeddedDocument.field_to_mongo)(field_name) | | | [`field_to_python`](#fiftyone.core.odm.embedded_document.EmbeddedDocument.field_to_python)(field_name, value) | | | [`from_dict`](#fiftyone.core.odm.embedded_document.EmbeddedDocument.from_dict)(d[, extended]) | Loads the document from a BSON/JSON dictionary. | | [`from_json`](#fiftyone.core.odm.embedded_document.EmbeddedDocument.from_json)(s) | Loads the document from a JSON string. | | [`get_field`](#fiftyone.core.odm.embedded_document.EmbeddedDocument.get_field)(field_name) | Gets the field of the document. | | [`get_text_score`](#fiftyone.core.odm.embedded_document.EmbeddedDocument.get_text_score)() | Get text score from text query | | [`has_field`](#fiftyone.core.odm.embedded_document.EmbeddedDocument.has_field)(field_name) | Determines whether the document has a field of the given name. | | [`iter_fields`](#fiftyone.core.odm.embedded_document.EmbeddedDocument.iter_fields)() | Returns an iterator over the `(name, value)` pairs of the public fields of the document. | | [`merge`](#fiftyone.core.odm.embedded_document.EmbeddedDocument.merge)(doc[, merge_lists, merge_dicts, overwrite]) | Merges the contents of the given document into this document. | | [`set_field`](#fiftyone.core.odm.embedded_document.EmbeddedDocument.set_field)(field_name, value[, create]) | Sets the value of a field of the document. | | [`to_dict`](#fiftyone.core.odm.embedded_document.EmbeddedDocument.to_dict)([extended]) | Serializes this document to a BSON/JSON dictionary. | | [`to_json`](#fiftyone.core.odm.embedded_document.EmbeddedDocument.to_json)([pretty_print]) | Serializes the document to a JSON string. | | [`to_mongo`](#fiftyone.core.odm.embedded_document.EmbeddedDocument.to_mongo)(\*args, \*\*kwargs) | Return as SON data ready for use with MongoDB. | | [`validate`](#fiftyone.core.odm.embedded_document.EmbeddedDocument.validate)([clean]) | Ensure that all fields' values are valid and that required fields are present. | **Classes:** | [`my_metaclass`](#fiftyone.core.odm.embedded_document.EmbeddedDocument.my_metaclass) | | |----------------------------------------------------------------------------------------|----| #### STRICT *= False* #### 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 #### 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 #### 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 #### 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 #### my_metaclass alias of `DocumentMetaclass` #### 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 #### to_mongo(\*args, \*\*kwargs) Return as SON data ready for use with MongoDB. #### 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. ### *exception* fiftyone.core.odm.embedded_document.DynamicEmbeddedDocumentException Bases: `Exception` Exception raised when an error occurs in a dynamic document operation. **Methods:** | [`add_note`](#fiftyone.core.odm.embedded_document.DynamicEmbeddedDocumentException.add_note)(object, /) | Exception.add_note(note) -- add a note to the exception | |---------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------| | [`with_traceback`](#fiftyone.core.odm.embedded_document.DynamicEmbeddedDocumentException.with_traceback)(object, /) | Exception.with_traceback(tb) -- set self._\_traceback_\_ to tb and return self. | **Attributes:** | [`args`](#fiftyone.core.odm.embedded_document.DynamicEmbeddedDocumentException.args) | | |----------------------------------------------------------------------------------------|----| #### add_note(object,) Exception.add_note(note) – add a note to the exception #### args #### with_traceback(object,) Exception.with_traceback(tb) – set self._\_traceback_\_ to tb and return self. ### *class* fiftyone.core.odm.embedded_document.DynamicEmbeddedDocument(\*args, \*\*kwargs) Bases: [`DynamicMixin`](fiftyone.core.odm.document.md#fiftyone.core.odm.document.DynamicMixin), [`BaseEmbeddedDocument`](#fiftyone.core.odm.embedded_document.BaseEmbeddedDocument), `DynamicEmbeddedDocument` Base class for dynamic documents that are embedded within other documents and therefore aren’t stored in their own collection in the database. Dynamic documents can have arbitrary fields added to them. **Attributes:** | [`STRICT`](#fiftyone.core.odm.embedded_document.DynamicEmbeddedDocument.STRICT) | | |-------------------------------------------------------------------------------------------|---------------------------------------------------------| | [`field_names`](#fiftyone.core.odm.embedded_document.DynamicEmbeddedDocument.field_names) | An ordered tuple of the public fields of this document. | **Methods:** | [`clean`](#fiftyone.core.odm.embedded_document.DynamicEmbeddedDocument.clean)() | Hook for doing document level data cleaning (usually validation or assignment) before validation is run. | |---------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------| | [`clear_field`](#fiftyone.core.odm.embedded_document.DynamicEmbeddedDocument.clear_field)(field_name) | Clears the field from the document. | | [`copy`](#fiftyone.core.odm.embedded_document.DynamicEmbeddedDocument.copy)() | Returns a deep copy of the document. | | [`fancy_repr`](#fiftyone.core.odm.embedded_document.DynamicEmbeddedDocument.fancy_repr)([class_name, select_fields, ...]) | Generates a customizable string representation of the document. | | [`field_to_mongo`](#fiftyone.core.odm.embedded_document.DynamicEmbeddedDocument.field_to_mongo)(field_name) | | | [`field_to_python`](#fiftyone.core.odm.embedded_document.DynamicEmbeddedDocument.field_to_python)(field_name, value) | | | [`from_dict`](#fiftyone.core.odm.embedded_document.DynamicEmbeddedDocument.from_dict)(d[, extended]) | Loads the document from a BSON/JSON dictionary. | | [`from_json`](#fiftyone.core.odm.embedded_document.DynamicEmbeddedDocument.from_json)(s) | Loads the document from a JSON string. | | [`get_field`](#fiftyone.core.odm.embedded_document.DynamicEmbeddedDocument.get_field)(field_name) | Gets the field of the document. | | [`get_text_score`](#fiftyone.core.odm.embedded_document.DynamicEmbeddedDocument.get_text_score)() | Get text score from text query | | [`has_field`](#fiftyone.core.odm.embedded_document.DynamicEmbeddedDocument.has_field)(field_name) | Determines whether the document has a field of the given name. | | [`iter_fields`](#fiftyone.core.odm.embedded_document.DynamicEmbeddedDocument.iter_fields)() | Returns an iterator over the `(name, value)` pairs of the public fields of the document. | | [`merge`](#fiftyone.core.odm.embedded_document.DynamicEmbeddedDocument.merge)(doc[, merge_lists, merge_dicts, overwrite]) | Merges the contents of the given document into this document. | | [`set_field`](#fiftyone.core.odm.embedded_document.DynamicEmbeddedDocument.set_field)(field_name, value[, create]) | Sets the value of a field of the document. | | [`to_dict`](#fiftyone.core.odm.embedded_document.DynamicEmbeddedDocument.to_dict)([extended]) | Serializes this document to a BSON/JSON dictionary. | | [`to_json`](#fiftyone.core.odm.embedded_document.DynamicEmbeddedDocument.to_json)([pretty_print]) | Serializes the document to a JSON string. | | [`to_mongo`](#fiftyone.core.odm.embedded_document.DynamicEmbeddedDocument.to_mongo)(\*args, \*\*kwargs) | Return as SON data ready for use with MongoDB. | | [`validate`](#fiftyone.core.odm.embedded_document.DynamicEmbeddedDocument.validate)([clean]) | Ensure that all fields' values are valid and that required fields are present. | **Classes:** | [`my_metaclass`](#fiftyone.core.odm.embedded_document.DynamicEmbeddedDocument.my_metaclass) | | |-----------------------------------------------------------------------------------------------|----| #### STRICT *= False* #### 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 #### 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 #### 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 #### 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 #### my_metaclass alias of `DocumentMetaclass` #### 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 #### to_mongo(\*args, \*\*kwargs) Return as SON data ready for use with MongoDB. #### 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.