fiftyone.core.odm.embedded_document#

Base classes for documents that back dataset contents.

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

Classes:

`BaseEmbeddedDocument`()	Base class for documents that are embedded within other documents and therefore are not stored in their own collection in the database.
`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`(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

Exception raised when an error occurs in a dynamic document operation.

class fiftyone.core.odm.embedded_document.BaseEmbeddedDocument#

Bases: 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`(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.

Attributes:

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, 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`
`field_names`	An ordered tuple of the public fields of this document.

Methods:

`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.
`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.
`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.
`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.
`to_mongo`(args, *kwargs)	Return as SON data ready for use with MongoDB.
`validate`([clean])	Ensure that all fields' values are valid and that required fields are present.

Classes:

my_metaclass

alias of DocumentMetaclass

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`	Exception.add_note(note) -- add a note to the exception
`with_traceback`	Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

Attributes:

args

add_note()#: Exception.add_note(note) – add a note to the exception

args#

with_traceback()#: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class fiftyone.core.odm.embedded_document.DynamicEmbeddedDocument(*args, **kwargs)#

Bases: DynamicMixin, 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`
`field_names`	An ordered tuple of the public fields of this document.

Methods:

`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.
`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.
`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.
`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.
`to_mongo`(args, *kwargs)	Return as SON data ready for use with MongoDB.
`validate`([clean])	Ensure that all fields' values are valid and that required fields are present.

Classes:

my_metaclass

alias of DocumentMetaclass

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.