# fiftyone.core.odm.embedded_document¶

Base classes for documents that back dataset contents.

Classes:

 BaseEmbeddedDocument 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. 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.
class 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.

Methods:

 clear_field(field_name) Clears the field from the document. 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. 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. 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, validate=True, dynamic=False)

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: fiftyone.core.odm.embedded_document.BaseEmbeddedDocument, mongoengine.document.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:

 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. 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. Loads the document from a JSON string. get_field(field_name) Gets the field of the document. Get text score from text query has_field(field_name) Determines whether the document has a field of the given name. 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 mongoengine.base.metaclasses.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 mongoengine.base.metaclasses.DocumentMetaclass Methods:

 mro Return a type’s method resolution order.
set_field(field_name, value, create=True, validate=True, dynamic=False)

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.

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

Bases: fiftyone.core.odm.document.DynamicMixin, fiftyone.core.odm.embedded_document.BaseEmbeddedDocument, mongoengine.document.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:

 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. 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. Loads the document from a JSON string. get_field(field_name) Gets the field of the document. Get text score from text query has_field(field_name) Determines whether the document has a field of the given name. 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) validate([clean]) Ensure that all fields’ values are valid and that required fields are present.

Classes:

 my_metaclass alias of mongoengine.base.metaclasses.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 mongoengine.base.metaclasses.DocumentMetaclass Methods:

 mro Return a type’s method resolution order.
set_field(field_name, value, create=True, validate=True, dynamic=False)

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)
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.