# fiftyone.core.odm¶

## Module contents¶

ODM package declaration.

Functions:

 aggregate(collection, pipelines) Executes one or more aggregations on a collection. Retrieves the database config. establish_db_conn(config) Establishes the database connection. Returns a database client. Returns a connection to the database. Returns an async database client. Returns an async connection to the database. Drops the database. Syncs all pending database writes to disk. Returns the list of available FiftyOne datasets. delete_dataset(name[, dry_run]) Deletes the dataset with the given name. delete_evaluation(name, eval_key[, dry_run]) Deletes the evaluation run with the given key from the dataset with the given name. delete_evaluations(name[, dry_run]) Deletes all evaluations from the dataset with the given name. delete_brain_run(name, brain_key[, dry_run]) Deletes the brain method run with the given key from the dataset with the given name. delete_brain_runs(name[, dry_run]) Deletes all brain method runs from the dataset with the given name. drop_collection(collection_name) Drops specified collection from the database. drop_orphan_collections([dry_run]) Drops all orphan collections from the database. drop_orphan_saved_views([dry_run]) Drops all orphan saved views from the database. drop_orphan_runs([dry_run]) Drops all orphan runs from the database. Returns a list of all collection names in the database. get_collection_stats(collection_name) Sets stats about the collection. stream_collection(collection_name) Streams the contents of the collection to stdout. count_documents(coll, pipeline) export_document(doc, json_path) Exports the document to disk in JSON format. export_collection(docs, json_dir_or_path[, …]) Exports the collection to disk in JSON format. import_document(json_path) Imports a document from JSON on disk. import_collection(json_dir_or_path[, key]) Imports the collection from JSON on disk. insert_documents(docs, coll[, ordered, …]) Inserts documents into a collection. bulk_write(ops, coll[, ordered]) Performs a batch of write operations on a collection. get_default_fields(cls[, include_private, …]) Gets the default fields present on all instances of the given DatasetMixin class. serialize_value(value[, extended]) Serializes the given value. deserialize_value(value) Deserializes the given value. validate_field_name(field_name[, …]) Verifies that the given field name is valid. create_field(name, ftype[, …]) Creates the field defined by the given specification. create_implied_field(path, value[, dynamic]) Creates the field for the given value. get_field_kwargs(field) Constructs the field keyword arguments dictionary for the given field. get_implied_field_kwargs(value[, dynamic]) Infers the field keyword arguments dictionary for a field that can hold the given value. validate_fields_match(name, field, …) Validates that the types of the given fields match.

Classes:

 SampleFieldDocument(*args, **kwargs) Description of a sample field. KeypointSkeleton(*args, **kwargs) Description of a keypoint skeleton. DatasetAppConfig(*args, **kwargs) Dataset-specific settings that customize how a dataset is visualized in the App. DatasetDocument(*args, **values) Backing document for datasets. SidebarGroupDocument(*args, **kwargs) Description of a sidebar group in the App. Document(*args, **values) Base class for documents that are stored in a MongoDB collection. SerializableDocument Mixin for documents that can be serialized in BSON or JSON format. 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. DatasetFrameDocument(*args, **values) NoDatasetFrameDocument(**kwargs) RunDocument(*args, **values) Backing document for dataset runs. DatasetSampleDocument(*args, **values) Base class for sample documents backing samples in datasets. NoDatasetSampleDocument(**kwargs) Backing document for samples that have not been added to a dataset. SavedViewDocument(*args, **values) Backing document for saved views.
fiftyone.core.odm.aggregate(collection, pipelines)

Executes one or more aggregations on a collection.

Multiple aggregations are executed using multiple threads, and their results are returned as lists rather than cursors.

Parameters
• collection – a pymongo.collection.Collection or motor.motor_asyncio.AsyncIOMotorCollection

• pipelines – a MongoDB aggregation pipeline or a list of pipelines

Returns

• If a single pipeline is provided, a pymongo.command_cursor.CommandCursor or motor.motor_asyncio.AsyncIOMotorCommandCursor is returned

• If multiple pipelines are provided, each cursor is extracted into a list and the list of lists is returned

fiftyone.core.odm.get_db_config()

Retrieves the database config.

Returns

a DatabaseConfigDocument

fiftyone.core.odm.establish_db_conn(config)

Establishes the database connection.

If fiftyone.config.database_uri is defined, then we connect to that URI. Otherwise, a fiftyone.core.service.DatabaseService is created.

Parameters
Raises
• ConnectionError – if a connection to mongod could not be established

• FiftyOneConfigError – if fiftyone.config.database_uri is not defined and mongod could not be found

• ServiceExecutableNotFound – if fiftyone.core.service.DatabaseService startup was attempted, but mongod was not found in fiftyone.db.bin

• RuntimeError – if the mongod found does not meet FiftyOne’s requirements, or validation could not occur

fiftyone.core.odm.get_db_client()

Returns a database client.

Returns

a pymongo.mongo_client.MongoClient

fiftyone.core.odm.get_db_conn()

Returns a connection to the database.

Returns

a pymongo.database.Database

fiftyone.core.odm.get_async_db_client()

Returns an async database client.

Returns

a motor.motor_asyncio.AsyncIOMotorClient

fiftyone.core.odm.get_async_db_conn()

Returns an async connection to the database.

Returns

a motor.motor_asyncio.AsyncIOMotorDatabase

fiftyone.core.odm.drop_database()

Drops the database.

fiftyone.core.odm.sync_database()

Syncs all pending database writes to disk.

fiftyone.core.odm.list_datasets()

Returns the list of available FiftyOne datasets.

This is a low-level implementation of dataset listing that does not call fiftyone.core.dataset.list_datasets(), which is helpful if a database may be corrupted.

Returns

a list of Dataset names

fiftyone.core.odm.delete_dataset(name, dry_run=False)

Deletes the dataset with the given name.

This is a low-level implementation of deletion that does not call fiftyone.core.dataset.load_dataset(), which is helpful if a dataset’s backing document or collections are corrupted and cannot be loaded via the normal pathways.

Parameters
• name – the name of the dataset

• dry_run (False) – whether to log the actions that would be taken but not perform them

fiftyone.core.odm.delete_evaluation(name, eval_key, dry_run=False)

Deletes the evaluation run with the given key from the dataset with the given name.

This is a low-level implementation of deletion that does not call fiftyone.core.dataset.load_dataset() or fiftyone.core.collections.SampleCollection.delete_evaluation(), which is helpful if a dataset’s backing document or collections are corrupted and cannot be loaded via the normal pathways.

Note that, as this method does not load fiftyone.core.runs.Run instances, it does not call fiftyone.core.runs.Run.cleanup().

Parameters
• name – the name of the dataset

• eval_key – the evaluation key

• dry_run (False) – whether to log the actions that would be taken but not perform them

fiftyone.core.odm.delete_evaluations(name, dry_run=False)

Deletes all evaluations from the dataset with the given name.

This is a low-level implementation of deletion that does not call fiftyone.core.dataset.load_dataset() or fiftyone.core.collections.SampleCollection.delete_evaluations(), which is helpful if a dataset’s backing document or collections are corrupted and cannot be loaded via the normal pathways.

Note that, as this method does not load fiftyone.core.runs.Run instances, it does not call fiftyone.core.runs.Run.cleanup().

Parameters
• name – the name of the dataset

• dry_run (False) – whether to log the actions that would be taken but not perform them

fiftyone.core.odm.delete_brain_run(name, brain_key, dry_run=False)

Deletes the brain method run with the given key from the dataset with the given name.

This is a low-level implementation of deletion that does not call fiftyone.core.dataset.load_dataset() or fiftyone.core.collections.SampleCollection.delete_brain_run(), which is helpful if a dataset’s backing document or collections are corrupted and cannot be loaded via the normal pathways.

Note that, as this method does not load fiftyone.core.runs.Run instances, it does not call fiftyone.core.runs.Run.cleanup().

Parameters
• name – the name of the dataset

• brain_key – the brain key

• dry_run (False) – whether to log the actions that would be taken but not perform them

fiftyone.core.odm.delete_brain_runs(name, dry_run=False)

Deletes all brain method runs from the dataset with the given name.

This is a low-level implementation of deletion that does not call fiftyone.core.dataset.load_dataset() or fiftyone.core.collections.SampleCollection.delete_brain_runs(), which is helpful if a dataset’s backing document or collections are corrupted and cannot be loaded via the normal pathways.

Note that, as this method does not load fiftyone.core.runs.Run instances, it does not call fiftyone.core.runs.Run.cleanup().

Parameters
• name – the name of the dataset

• dry_run (False) – whether to log the actions that would be taken but not perform them

fiftyone.core.odm.drop_collection(collection_name)

Drops specified collection from the database.

Parameters

collection_name – the collection name

fiftyone.core.odm.drop_orphan_collections(dry_run=False)

Drops all orphan collections from the database.

Orphan collections are collections that are not associated with any known dataset or other collections used by FiftyOne.

Parameters

dry_run (False) – whether to log the actions that would be taken but not perform them

fiftyone.core.odm.drop_orphan_saved_views(dry_run=False)

Drops all orphan saved views from the database.

Orphan saved views are saved view documents that are not associated with any known dataset or other collections used by FiftyOne.

Parameters

dry_run (False) – whether to log the actions that would be taken but not perform them

fiftyone.core.odm.drop_orphan_runs(dry_run=False)

Drops all orphan runs from the database.

Orphan runs are runs that are not associated with any known dataset or other collections used by FiftyOne.

Parameters

dry_run (False) – whether to log the actions that would be taken but not perform them

fiftyone.core.odm.list_collections()

Returns a list of all collection names in the database.

Returns

a list of all collection names

fiftyone.core.odm.get_collection_stats(collection_name)

Parameters

collection_name – the name of the collection

Returns

a stats dict

fiftyone.core.odm.stream_collection(collection_name)

Streams the contents of the collection to stdout.

Parameters

collection_name – the name of the collection

fiftyone.core.odm.count_documents(coll, pipeline)
fiftyone.core.odm.export_document(doc, json_path)

Exports the document to disk in JSON format.

Parameters
• doc – a BSON document dict

• json_path – the path to write the JSON file

fiftyone.core.odm.export_collection(docs, json_dir_or_path, key='documents', patt='{idx:06d}-{id}.json', num_docs=None)

Exports the collection to disk in JSON format.

Parameters
• docs – an iterable containing the documents to export

• json_dir_or_path – the path to write a single JSON file containing the entire collection, or a directory in which to write per-document JSON files

• key ("documents") – the field name under which to store the documents when json_path is a single JSON file

• ("{idx (patt) – 06d}-{id}.json”): a filename pattern to use when json_path is a directory. The pattern may contain idx to refer to the index of the document in docs or id to refer to the document’s ID

• num_docs (None) – the total number of documents. If omitted, this must be computable via len(docs)

fiftyone.core.odm.import_document(json_path)

Imports a document from JSON on disk.

Parameters

json_path – the path to the document

Returns

a BSON document dict

fiftyone.core.odm.import_collection(json_dir_or_path, key='documents')

Imports the collection from JSON on disk.

Parameters
• json_dir_or_path – the path to a JSON file on disk, or a directory containing per-document JSON files

• key ("documents") – the field name under which the documents are stored when json_path is a single JSON file

Returns

a tuple of

• an iterable of BSON documents

• the number of documents

fiftyone.core.odm.insert_documents(docs, coll, ordered=False, progress=False, num_docs=None)

Inserts documents into a collection.

The _id field of the input documents will be populated if it is not already set.

Parameters
• docs – an iterable of BSON document dicts

• coll – a pymongo collection

• ordered (False) – whether the documents must be inserted in order

• progress (False) – whether to render a progress bar tracking the insertion

• num_docs (None) – the total number of documents. Only used when progress=True. If omitted, this will be computed via len(docs), if possible

Returns

a list of IDs of the inserted documents

fiftyone.core.odm.bulk_write(ops, coll, ordered=False)

Performs a batch of write operations on a collection.

Parameters
• ops – a list of pymongo operations

• coll – a pymongo collection

• ordered (False) – whether the operations must be performed in order

class fiftyone.core.odm.SampleFieldDocument(*args, **kwargs)

Description of a sample field.

Attributes:

 STRICT db_field A unicode string field. description A unicode string field. embedded_doc_type A unicode string field. field_names An ordered tuple of the public fields of this document. fields A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database. ftype A unicode string field. info A dictionary field that wraps a standard Python dictionary. name A unicode string field. subfield A unicode string field.

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. from_field(field) Creates a SampleFieldDocument for a field. 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. Creates the fiftyone.core.fields.Field specified by this document. 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
name

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

ftype

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

embedded_doc_type

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

subfield

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

fields

A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database.

If this field is not set, its default value is [].

Parameters
• field (None) – an optional Field instance describing the type of the list elements

• description (None) – an optional description

• info (None) – an optional info dict

db_field

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

description

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

info

A dictionary field that wraps a standard Python dictionary.

If this field is not set, its default value is {}.

Parameters
• field (None) – an optional Field instance describing the type of the values in the dict

• description (None) – an optional description

• info (None) – an optional info dict

to_field()

Creates the fiftyone.core.fields.Field specified by this document.

Returns
classmethod from_field(field)

Creates a SampleFieldDocument for a field.

Parameters

field – a fiftyone.core.fields.Field instance

Returns
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
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
classmethod from_json(s)

Loads the document from a JSON string.

Returns
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.KeypointSkeleton(*args, **kwargs)

Description of a keypoint skeleton.

Keypoint skeletons can be associated with fiftyone.core.labels.Keypoint or fiftyone.core.labels.Keypoints fields whose points attributes all contain a fixed number of semantically ordered points.

The edges argument contains lists of integer indexes that define the connectivity of the points in the skeleton, and the optional labels argument defines the label strings for each node in the skeleton.

For example, the skeleton below is defined by edges between the following nodes:

left hand <-> left shoulder <-> right shoulder <-> right hand
left eye <-> right eye <-> mouth


Example:

import fiftyone as fo

# A skeleton for an object made of 7 points
skeleton = fo.KeypointSkeleton(
labels=[
"left hand" "left shoulder", "right shoulder", "right hand",
"left eye", "right eye", "mouth",
],
edges=[[0, 1, 2, 3], [4, 5, 6]],
)

Parameters
• labels (None) – an optional list of label strings for each node

• edges – a list of lists of integer indexes defining the connectivity between nodes

Attributes:

 STRICT edges A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database. field_names An ordered tuple of the public fields of this document. labels A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database.

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
labels

A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database.

If this field is not set, its default value is [].

Parameters
• field (None) – an optional Field instance describing the type of the list elements

• description (None) – an optional description

• info (None) – an optional info dict

edges

A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database.

If this field is not set, its default value is [].

Parameters
• field (None) – an optional Field instance describing the type of the list elements

• description (None) – an optional description

• info (None) – an optional info dict

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
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
classmethod from_json(s)

Loads the document from a JSON string.

Returns
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.DatasetAppConfig(*args, **kwargs)

Dataset-specific settings that customize how a dataset is visualized in the App.

Parameters
• media_fields (["filepath"]) – the list of sample fields that contain media and should be available to choose from the App’s settings menus

• grid_media_field ("filepath") – the default sample field from which to serve media in the App’s grid view

• modal_media_field ("filepath") – the default sample field from which to serve media in the App’s modal view

• sidebar_mode (None) – an optional default mode for the App sidebar. Supported values are ("fast", "all", "best")

• sidebar_groups (None) – an optional list of SidebarGroupDocument describing sidebar groups to use in the App

• plugins ({}) –

an optional dict mapping plugin names to plugin configuration dicts. Builtin plugins include:

Attributes:

 STRICT field_names An ordered tuple of the public fields of this document. grid_media_field A unicode string field. media_fields A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database. modal_media_field A unicode string field. plugins A dictionary field that wraps a standard Python dictionary. sidebar_groups A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database. sidebar_mode A unicode string field.

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. default_sidebar_groups(sample_collection) Generates the default sidebar_groups for the given collection. 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. Determines whether this app config differs from the default one. 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
media_fields

A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database.

If this field is not set, its default value is [].

Parameters
• field (None) – an optional Field instance describing the type of the list elements

• description (None) – an optional description

• info (None) – an optional info dict

grid_media_field

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

modal_media_field

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

sidebar_mode

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

sidebar_groups

A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database.

If this field is not set, its default value is [].

Parameters
• field (None) – an optional Field instance describing the type of the list elements

• description (None) – an optional description

• info (None) – an optional info dict

plugins

A dictionary field that wraps a standard Python dictionary.

If this field is not set, its default value is {}.

Parameters
• field (None) – an optional Field instance describing the type of the values in the dict

• description (None) – an optional description

• info (None) – an optional info dict

static default_sidebar_groups(sample_collection)

Generates the default sidebar_groups for the given collection.

Examples:

import fiftyone as fo
import fiftyone.zoo as foz

sidebar_groups = fo.DatasetAppConfig.default_sidebar_groups(dataset)
dataset.app_config.sidebar_groups = sidebar_groups
print(dataset.app_config)

Parameters

sample_collection – a fiftyone.core.collections.SampleCollection

Returns

a list of SidebarGroupDocument instances

is_custom()

Determines whether this app config differs from the default one.

Returns

True/False

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
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
classmethod from_json(s)

Loads the document from a JSON string.

Returns
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.DatasetDocument(*args, **values)

Backing document for datasets.

Miscellaneous:

Attributes:

 STRICT annotation_runs A dictionary field that wraps a standard Python dictionary. app_config A field that stores instances of a given type of fiftyone.core.odm.BaseEmbeddedDocument object. brain_methods A dictionary field that wraps a standard Python dictionary. classes A dictionary field that wraps a standard Python dictionary. created_at A datetime field. default_classes A ListField that stores class label strings. default_group_slice A unicode string field. default_mask_targets A DictField that stores mapping between integer keys or RGB string hex keys and string targets. default_skeleton A field that stores instances of a given type of fiftyone.core.odm.BaseEmbeddedDocument object. description A unicode string field. evaluations A dictionary field that wraps a standard Python dictionary. field_names An ordered tuple of the public fields of this document. frame_collection_name A unicode string field. frame_fields A field that stores a list of a given type of fiftyone.core.odm.BaseEmbeddedDocument objects. group_field A unicode string field. group_media_types A dictionary field that wraps a standard Python dictionary. id A field wrapper around MongoDB’s ObjectIds. in_db Whether the document has been inserted into the database. info A dictionary field that wraps a standard Python dictionary. last_loaded_at A datetime field. mask_targets A dictionary field that wraps a standard Python dictionary. media_type A unicode string field. name A unicode string field. objects([q_obj]) persistent A boolean field. pk Get the primary key. sample_collection_name A unicode string field. sample_fields A field that stores a list of a given type of fiftyone.core.odm.BaseEmbeddedDocument objects. saved_views A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database. skeletons A dictionary field that wraps a standard Python dictionary. slug A unicode string field. tags A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database. version A unicode string field.

Methods:

 cascade_save(**kwargs) Recursively save any references and generic references on the document. 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. Compares the indexes defined in MongoEngine with the ones existing in the database. 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. Drops the entire collection associated with this Document type from the database. ensure_index(key_or_list[, background]) Ensure that the given indexes are in place. 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. 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. 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([upsert, validate, clean, safe]) Saves 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. Returns an instance of DBRef useful in __raw__ queries. to_dict(*args[, no_dereference]) 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 mongoengine.base.metaclasses.TopLevelDocumentMetaclass
name

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

slug

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

version

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

created_at

A datetime field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

last_loaded_at

A datetime field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

sample_collection_name

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

frame_collection_name

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

persistent

A boolean field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

media_type

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

group_field

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

group_media_types

A dictionary field that wraps a standard Python dictionary.

If this field is not set, its default value is {}.

Parameters
• field (None) – an optional Field instance describing the type of the values in the dict

• description (None) – an optional description

• info (None) – an optional info dict

default_group_slice

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

tags

A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database.

If this field is not set, its default value is [].

Parameters
• field (None) – an optional Field instance describing the type of the list elements

• description (None) – an optional description

• info (None) – an optional info dict

description

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

info

A dictionary field that wraps a standard Python dictionary.

If this field is not set, its default value is {}.

Parameters
• field (None) – an optional Field instance describing the type of the values in the dict

• description (None) – an optional description

• info (None) – an optional info dict

app_config

A field that stores instances of a given type of fiftyone.core.odm.BaseEmbeddedDocument object.

Parameters
classes

A dictionary field that wraps a standard Python dictionary.

If this field is not set, its default value is {}.

Parameters
• field (None) – an optional Field instance describing the type of the values in the dict

• description (None) – an optional description

• info (None) – an optional info dict

default_classes

A ListField that stores class label strings.

If this field is not set, its default value is [].

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

mask_targets

A dictionary field that wraps a standard Python dictionary.

If this field is not set, its default value is {}.

Parameters
• field (None) – an optional Field instance describing the type of the values in the dict

• description (None) – an optional description

• info (None) – an optional info dict

default_mask_targets

A DictField that stores mapping between integer keys or RGB string hex keys and string targets.

If this field is not set, its default value is {}.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

skeletons

A dictionary field that wraps a standard Python dictionary.

If this field is not set, its default value is {}.

Parameters
• field (None) – an optional Field instance describing the type of the values in the dict

• description (None) – an optional description

• info (None) – an optional info dict

default_skeleton

A field that stores instances of a given type of fiftyone.core.odm.BaseEmbeddedDocument object.

Parameters
sample_fields

A field that stores a list of a given type of fiftyone.core.odm.BaseEmbeddedDocument objects.

Parameters
frame_fields

A field that stores a list of a given type of fiftyone.core.odm.BaseEmbeddedDocument objects.

Parameters
saved_views

A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database.

If this field is not set, its default value is [].

Parameters
• field (None) – an optional Field instance describing the type of the list elements

• description (None) – an optional description

• info (None) – an optional info dict

annotation_runs

A dictionary field that wraps a standard Python dictionary.

If this field is not set, its default value is {}.

Parameters
• field (None) – an optional Field instance describing the type of the values in the dict

• description (None) – an optional description

• info (None) – an optional info dict

brain_methods

A dictionary field that wraps a standard Python dictionary.

If this field is not set, its default value is {}.

Parameters
• field (None) – an optional Field instance describing the type of the values in the dict

• description (None) – an optional description

• info (None) – an optional info dict

evaluations

A dictionary field that wraps a standard Python dictionary.

If this field is not set, its default value is {}.

Parameters
• field (None) – an optional Field instance describing the type of the values in the dict

• description (None) – an optional description

• info (None) – an optional info dict

to_dict(*args, no_dereference=False, **kwargs)

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

exception DoesNotExist

Bases: mongoengine.errors.DoesNotExist

args
with_traceback()

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

exception MultipleObjectsReturned

Bases: mongoengine.errors.MultipleObjectsReturned

args
with_traceback()

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

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
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_index(key_or_list, background=False, **kwargs)

Ensure that the given indexes are in place. Deprecated in favour of create_index.

Parameters
• key_or_list – 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

classmethod ensure_indexes()

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

Global defaults can be set in the meta - see 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.

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
classmethod from_json(s)

Loads the document from a JSON string.

Returns
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

id

A field wrapper around MongoDB’s ObjectIds.

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 mongoengine.base.metaclasses.TopLevelDocumentMetaclass Methods:

 get_auto_id_names(new_class) Find a name for the automatic ID field for the given new class. mro Return a type’s method resolution order.
objects(q_obj=None, **query) = []
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(upsert=False, validate=True, clean=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

• clean (True) – whether to call the document’s clean() method. Only applicable when validate is True

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

Returns

self

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, 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

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

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

Use switch_collection if you need to read from another collection

to_dbref()

Returns an instance of DBRef useful in __raw__ queries.

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.SidebarGroupDocument(*args, **kwargs)

Description of a sidebar group in the App.

Parameters
• name – the name of the sidebar group

• paths ([]) – the list of field or embedded.field.name paths in the group

• expanded (None) – whether this group should be expanded by default

Attributes:

 STRICT expanded A boolean field. field_names An ordered tuple of the public fields of this document. name A unicode string field. paths A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database.

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
name

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

paths

A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database.

If this field is not set, its default value is [].

Parameters
• field (None) – an optional Field instance describing the type of the list elements

• description (None) – an optional description

• info (None) – an optional info dict

expanded

A boolean field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

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
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
classmethod from_json(s)

Loads the document from a JSON string.

Returns
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.Document(*args, **values)

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

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. 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. Compares the indexes defined in MongoEngine with the ones existing in the database. 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. Drops the entire collection associated with this Document type from the database. ensure_index(key_or_list[, background]) Ensure that the given indexes are in place. 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. 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. 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([upsert, validate, clean, safe]) Saves 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. 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 mongoengine.base.metaclasses.TopLevelDocumentMetaclass
save(upsert=False, validate=True, clean=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

• clean (True) – whether to call the document’s clean() method. Only applicable when validate is True

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

Returns

self

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
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_index(key_or_list, background=False, **kwargs)

Ensure that the given indexes are in place. Deprecated in favour of create_index.

Parameters
• key_or_list – 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

classmethod ensure_indexes()

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

Global defaults can be set in the meta - see 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.

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
classmethod from_json(s)

Loads the document from a JSON string.

Returns
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 mongoengine.base.metaclasses.TopLevelDocumentMetaclass Methods:

 get_auto_id_names(new_class) Find a name for the automatic ID field for the given new class. mro Return a type’s method resolution order.
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

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, 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

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

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

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

Bases: object

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

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. 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.
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
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
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
class fiftyone.core.odm.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
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
classmethod from_json(s)

Loads the document from a JSON string.

Returns
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.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
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
classmethod from_json(s)

Loads the document from a JSON string.

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

class fiftyone.core.odm.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
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
classmethod from_json(s)

Loads the document from a JSON string.

Returns
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.DatasetFrameDocument(*args, **values)

Attributes:

 STRICT collection_name field_names frame_number A video frame number field. id An Object ID field. in_db Whether the document has been inserted into the database. pk Get the primary key.

Methods:

 add_field(path, ftype[, embedded_doc_type, …]) Adds a new field or embedded field to the document, if necessary. add_implied_field(path, value[, …]) Adds the field or embedded field to the document, if necessary, inferring the field type from the provided value. cascade_save(**kwargs) Recursively save any references and generic references on the document. Hook for doing document level data cleaning (usually validation or assignment) before validation is run. clear_field(field_name) Compares the indexes defined in MongoEngine with the ones existing in the database. 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. Drops the entire collection associated with this Document type from the database. ensure_index(key_or_list[, background]) Ensure that the given indexes are in place. 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. Loads the document from a JSON string. get_field(field_name) get_field_schema([ftype, embedded_doc_type, …]) Returns a schema dictionary describing the fields of this document. Get text score from text query has_field(field_name) Returns an iterator over the (name, value) pairs of the public fields of the document. 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. merge_field_schema(schema[, expand_schema, …]) Merges the field schema 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([upsert, validate, clean, safe]) Saves 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, …]) 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. 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 mongoengine.base.metaclasses.TopLevelDocumentMetaclass
id

An Object ID field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

frame_number

A video frame number field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

STRICT = False
classmethod add_field(path, ftype, embedded_doc_type=None, subfield=None, fields=None, description=None, info=None, expand_schema=True, recursive=True, validate=True, **kwargs)

Adds a new field or embedded field to the document, if necessary.

Parameters
Returns

True/False whether one or more fields or embedded fields were added to the document or its children

Raises

ValueError – if a field in the schema is not compliant with an existing field of the same name

classmethod add_implied_field(path, value, expand_schema=True, dynamic=False, recursive=True, validate=True)

Adds the field or embedded field to the document, if necessary, inferring the field type from the provided value.

Parameters
• path – the field name or embedded.field.name

• value – the field value

• expand_schema (True) – whether to add new fields to the schema (True) or simply validate that the field already exists with a consistent type (False)

• dynamic (False) – whether to declare dynamic embedded document fields

• recursive (True) – whether to recursively add embedded document fields

• validate (True) – whether to validate the field against an existing field at the same path

Returns

True/False whether one or more fields or embedded fields were added to the document or its children

Raises

ValueError – if a field in the schema is not compliant with an existing field of the same name

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)
property collection_name
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
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_index(key_or_list, background=False, **kwargs)

Ensure that the given indexes are in place. Deprecated in favour of create_index.

Parameters
• key_or_list – 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

classmethod ensure_indexes()

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

Global defaults can be set in the meta - see 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.

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
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
classmethod from_json(s)

Loads the document from a JSON string.

Returns
get_field(field_name)
classmethod get_field_schema(ftype=None, embedded_doc_type=None, include_private=False)

Returns a schema dictionary describing the fields of this document.

If the document belongs to a dataset, the schema will apply to all documents in the collection.

Parameters
• ftype (None) – an optional field type or iterable of field types to which to restrict the returned schema. Must be subclass(es) of fiftyone.core.fields.Field

• embedded_doc_type (None) – an optional embedded document type or iterable of types to which to restrict the returned schema. Must be subclass(es) of fiftyone.core.odm.BaseEmbeddedDocument

• include_private (False) – whether to include fields that start with _ in the returned schema

Returns

a dictionary mapping field names to field types

get_text_score()

Get text score from text query

has_field(field_name)
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

classmethod merge_field_schema(schema, expand_schema=True, recursive=True, validate=True)

Merges the field schema into this document.

Parameters
• schema – a dictionary mapping field names or embedded.field.namesto fiftyone.core.fields.Field instances

• expand_schema (True) – whether to add new fields to the schema (True) or simply validate that fields already exist with consistent types (False)

• recursive (True) – whether to recursively merge embedded document fields

• validate (True) – whether to validate the field against an existing field at the same path

Returns

True/False whether any new fields were added

Raises

ValueError – if a field in the schema is not compliant with an existing field of the same name or a new field is found but expand_schema == False

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 mongoengine.base.metaclasses.TopLevelDocumentMetaclass Methods:

 get_auto_id_names(new_class) Find a name for the automatic ID field for the given new class. mro Return a type’s method resolution order.
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(upsert=False, validate=True, clean=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

• clean (True) – whether to call the document’s clean() method. Only applicable when validate is True

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

Returns

self

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, validate=True, dynamic=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

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

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.NoDatasetFrameDocument(**kwargs)

Methods:

 clear_field(field_name) Returns a deep copy of the document. fancy_repr([class_name, select_fields, …]) Generates a customizable string representation of the document. from_dict(d[, extended]) Loads the document from a BSON/JSON dictionary. Loads the document from a JSON string. get_field(field_name) has_field(field_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, …]) to_dict([extended]) to_json([pretty_print]) Serializes the document to a JSON string.

Attributes:

default_fields = {'_dataset_id': <fiftyone.core.fields.ObjectIdField object>, '_sample_id': <fiftyone.core.fields.ObjectIdField object>, 'frame_number': <fiftyone.core.fields.FrameNumberField object>, 'id': <fiftyone.core.fields.ObjectIdField object>}
default_fields_ordered = ('id', 'frame_number', '_sample_id', '_dataset_id')
clear_field(field_name)
copy()

Returns a deep copy of the document.

Returns
delete()
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
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
classmethod from_json(s)

Loads the document from a JSON string.

Returns
get_field(field_name)
has_field(field_name)
property in_db
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

reload()
save()
set_field(field_name, value, create=True, validate=True, dynamic=False)
to_dict(extended=False)
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

fiftyone.core.odm.get_default_fields(cls, include_private=False, use_db_fields=False)

Gets the default fields present on all instances of the given DatasetMixin class.

Parameters
• cls – the DatasetMixin class

• include_private (False) – whether to include fields starting with _

• use_db_fields (False) – whether to return database fields rather than user-facing fields, when applicable

Returns

a tuple of field names

class fiftyone.core.odm.RunDocument(*args, **values)

Backing document for dataset runs.

Miscellaneous:

Attributes:

 STRICT config A dictionary field that wraps a standard Python dictionary. dataset_id An Object ID field. field_names An ordered tuple of the public fields of this document. id A field wrapper around MongoDB’s ObjectIds. in_db Whether the document has been inserted into the database. key A unicode string field. objects([q_obj]) pk Get the primary key. results A GridFS storage field. timestamp A datetime field. version A unicode string field. view_stages A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database.

Methods:

 cascade_save(**kwargs) Recursively save any references and generic references on the document. 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. Compares the indexes defined in MongoEngine with the ones existing in the database. 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. Drops the entire collection associated with this Document type from the database. ensure_index(key_or_list[, background]) Ensure that the given indexes are in place. 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. 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. 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([upsert, validate, clean, safe]) Saves 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. 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 mongoengine.base.metaclasses.TopLevelDocumentMetaclass
dataset_id

An Object ID field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

key

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

version

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

timestamp

A datetime field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

config

A dictionary field that wraps a standard Python dictionary.

If this field is not set, its default value is {}.

Parameters
• field (None) – an optional Field instance describing the type of the values in the dict

• description (None) – an optional description

• info (None) – an optional info dict

view_stages

A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database.

If this field is not set, its default value is [].

Parameters
• field (None) – an optional Field instance describing the type of the list elements

• description (None) – an optional description

• info (None) – an optional info dict

results

A GridFS storage field.

exception DoesNotExist

Bases: mongoengine.errors.DoesNotExist

args
with_traceback()

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

exception MultipleObjectsReturned

Bases: mongoengine.errors.MultipleObjectsReturned

args
with_traceback()

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

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
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_index(key_or_list, background=False, **kwargs)

Ensure that the given indexes are in place. Deprecated in favour of create_index.

Parameters
• key_or_list – 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

classmethod ensure_indexes()

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

Global defaults can be set in the meta - see 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.

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
classmethod from_json(s)

Loads the document from a JSON string.

Returns
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

id

A field wrapper around MongoDB’s ObjectIds.

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 mongoengine.base.metaclasses.TopLevelDocumentMetaclass Methods:

 get_auto_id_names(new_class) Find a name for the automatic ID field for the given new class. mro Return a type’s method resolution order.
objects(q_obj=None, **query) = []
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(upsert=False, validate=True, clean=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

• clean (True) – whether to call the document’s clean() method. Only applicable when validate is True

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

Returns

self

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, 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

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

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

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.DatasetSampleDocument(*args, **values)

Base class for sample documents backing samples in datasets.

All fiftyone.core.dataset.Dataset._sample_doc_cls classes inherit from this class.

Attributes:

 STRICT collection_name field_names filepath A unicode string field. id An Object ID field. in_db Whether the document has been inserted into the database. media_type metadata A field that stores instances of a given type of fiftyone.core.odm.BaseEmbeddedDocument object. pk Get the primary key. tags A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database.

Methods:

 add_field(path, ftype[, embedded_doc_type, …]) Adds a new field or embedded field to the document, if necessary. add_implied_field(path, value[, …]) Adds the field or embedded field to the document, if necessary, inferring the field type from the provided value. cascade_save(**kwargs) Recursively save any references and generic references on the document. Hook for doing document level data cleaning (usually validation or assignment) before validation is run. clear_field(field_name) Compares the indexes defined in MongoEngine with the ones existing in the database. 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. Drops the entire collection associated with this Document type from the database. ensure_index(key_or_list[, background]) Ensure that the given indexes are in place. 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. Loads the document from a JSON string. get_field(field_name) get_field_schema([ftype, embedded_doc_type, …]) Returns a schema dictionary describing the fields of this document. Get text score from text query has_field(field_name) Returns an iterator over the (name, value) pairs of the public fields of the document. 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. merge_field_schema(schema[, expand_schema, …]) Merges the field schema 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([upsert, validate, clean, safe]) Saves 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, …]) 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. 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 mongoengine.base.metaclasses.TopLevelDocumentMetaclass
id

An Object ID field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

filepath

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

tags

A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database.

If this field is not set, its default value is [].

Parameters
• field (None) – an optional Field instance describing the type of the list elements

• description (None) – an optional description

• info (None) – an optional info dict

metadata

A field that stores instances of a given type of fiftyone.core.odm.BaseEmbeddedDocument object.

Parameters
property media_type
STRICT = False
classmethod add_field(path, ftype, embedded_doc_type=None, subfield=None, fields=None, description=None, info=None, expand_schema=True, recursive=True, validate=True, **kwargs)

Adds a new field or embedded field to the document, if necessary.

Parameters
Returns

True/False whether one or more fields or embedded fields were added to the document or its children

Raises

ValueError – if a field in the schema is not compliant with an existing field of the same name

classmethod add_implied_field(path, value, expand_schema=True, dynamic=False, recursive=True, validate=True)

Adds the field or embedded field to the document, if necessary, inferring the field type from the provided value.

Parameters
• path – the field name or embedded.field.name

• value – the field value

• expand_schema (True) – whether to add new fields to the schema (True) or simply validate that the field already exists with a consistent type (False)

• dynamic (False) – whether to declare dynamic embedded document fields

• recursive (True) – whether to recursively add embedded document fields

• validate (True) – whether to validate the field against an existing field at the same path

Returns

True/False whether one or more fields or embedded fields were added to the document or its children

Raises

ValueError – if a field in the schema is not compliant with an existing field of the same name

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)
property collection_name
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
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_index(key_or_list, background=False, **kwargs)

Ensure that the given indexes are in place. Deprecated in favour of create_index.

Parameters
• key_or_list – 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

classmethod ensure_indexes()

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

Global defaults can be set in the meta - see 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.

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
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
classmethod from_json(s)

Loads the document from a JSON string.

Returns
get_field(field_name)
classmethod get_field_schema(ftype=None, embedded_doc_type=None, include_private=False)

Returns a schema dictionary describing the fields of this document.

If the document belongs to a dataset, the schema will apply to all documents in the collection.

Parameters
• ftype (None) – an optional field type or iterable of field types to which to restrict the returned schema. Must be subclass(es) of fiftyone.core.fields.Field

• embedded_doc_type (None) – an optional embedded document type or iterable of types to which to restrict the returned schema. Must be subclass(es) of fiftyone.core.odm.BaseEmbeddedDocument

• include_private (False) – whether to include fields that start with _ in the returned schema

Returns

a dictionary mapping field names to field types

get_text_score()

Get text score from text query

has_field(field_name)
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

classmethod merge_field_schema(schema, expand_schema=True, recursive=True, validate=True)

Merges the field schema into this document.

Parameters
• schema – a dictionary mapping field names or embedded.field.namesto fiftyone.core.fields.Field instances

• expand_schema (True) – whether to add new fields to the schema (True) or simply validate that fields already exist with consistent types (False)

• recursive (True) – whether to recursively merge embedded document fields

• validate (True) – whether to validate the field against an existing field at the same path

Returns

True/False whether any new fields were added

Raises

ValueError – if a field in the schema is not compliant with an existing field of the same name or a new field is found but expand_schema == False

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 mongoengine.base.metaclasses.TopLevelDocumentMetaclass Methods:

 get_auto_id_names(new_class) Find a name for the automatic ID field for the given new class. mro Return a type’s method resolution order.
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(upsert=False, validate=True, clean=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

• clean (True) – whether to call the document’s clean() method. Only applicable when validate is True

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

Returns

self

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, validate=True, dynamic=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

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

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.NoDatasetSampleDocument(**kwargs)

Backing document for samples that have not been added to a dataset.

Methods:

 clear_field(field_name) Returns a deep copy of the document. fancy_repr([class_name, select_fields, …]) Generates a customizable string representation of the document. from_dict(d[, extended]) Loads the document from a BSON/JSON dictionary. Loads the document from a JSON string. get_field(field_name) has_field(field_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, …]) to_dict([extended]) to_json([pretty_print]) Serializes the document to a JSON string.

Attributes:

default_fields = {'_dataset_id': <fiftyone.core.fields.ObjectIdField object>, '_media_type': <fiftyone.core.fields.StringField object>, '_rand': <fiftyone.core.fields.FloatField object>, 'filepath': <fiftyone.core.fields.StringField object>, 'id': <fiftyone.core.fields.ObjectIdField object>, 'metadata': <fiftyone.core.fields.EmbeddedDocumentField object>, 'tags': <fiftyone.core.fields.ListField object>}
default_fields_ordered = ('id', 'filepath', 'tags', 'metadata', '_media_type', '_rand', '_dataset_id')
property media_type
clear_field(field_name)
copy()

Returns a deep copy of the document.

Returns
delete()
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
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
classmethod from_json(s)

Loads the document from a JSON string.

Returns
get_field(field_name)
has_field(field_name)
property in_db
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

reload()
save()
set_field(field_name, value, create=True, validate=True, dynamic=False)
to_dict(extended=False)
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

fiftyone.core.odm.serialize_value(value, extended=False)

Serializes the given value.

Parameters
• value – the value

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

Returns

the serialized value

fiftyone.core.odm.deserialize_value(value)

Deserializes the given value.

Parameters

value – the serialized value

Returns

the value

fiftyone.core.odm.validate_field_name(field_name, media_type=None, is_frame_field=False)

Verifies that the given field name is valid.

Parameters
• field_name – the field name

• media_type (None) – the media type of the sample, if known

• is_frame_field (False) – whether this is a frame-level field

Raises

ValueError – if the field name is invalid

fiftyone.core.odm.create_field(name, ftype, embedded_doc_type=None, subfield=None, fields=None, db_field=None, description=None, info=None, **kwargs)

Creates the field defined by the given specification.

Note

This method is used exclusively to create user-defined (non-default) fields. Any parameters accepted here must be stored on fiftyone.core.odm.dataset.SampleFieldDocument or else datasets will “lose” any additional decorations when they are loaded from the database.

Parameters
Returns
fiftyone.core.odm.create_implied_field(path, value, dynamic=False)

Creates the field for the given value.

Parameters
• path – the field name or path

• value – a value

• dynamic (False) – whether to declare dynamic embedded document fields

Returns
fiftyone.core.odm.get_field_kwargs(field)

Constructs the field keyword arguments dictionary for the given field.

Parameters
Returns

a field specification dict

fiftyone.core.odm.get_implied_field_kwargs(value, dynamic=False)

Infers the field keyword arguments dictionary for a field that can hold the given value.

Parameters
• value – a value

• dynamic (False) – whether to declare dynamic embedded document fields

Returns

a field specification dict

fiftyone.core.odm.validate_fields_match(name, field, existing_field)

Validates that the types of the given fields match.

Embedded document fields are not validated, if applicable.

Parameters
Raises

ValueError – if the fields do not match

class fiftyone.core.odm.SavedViewDocument(*args, **values)

Backing document for saved views.

Miscellaneous:

Attributes:

 STRICT color A string field that holds a hex color string like ‘#FF6D04’. created_at A datetime field. dataset_id An Object ID field. description A unicode string field. field_names An ordered tuple of the public fields of this document. id A field wrapper around MongoDB’s ObjectIds. in_db Whether the document has been inserted into the database. last_loaded_at A datetime field. last_modified_at A datetime field. name A unicode string field. objects([q_obj]) pk Get the primary key. slug A unicode string field. view_stages A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database.

Methods:

 cascade_save(**kwargs) Recursively save any references and generic references on the document. 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. Compares the indexes defined in MongoEngine with the ones existing in the database. 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. Drops the entire collection associated with this Document type from the database. ensure_index(key_or_list[, background]) Ensure that the given indexes are in place. 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. 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. 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([upsert, validate, clean, safe]) Saves 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. 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 mongoengine.base.metaclasses.TopLevelDocumentMetaclass
dataset_id

An Object ID field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

name

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

description

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

slug

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

color

A string field that holds a hex color string like ‘#FF6D04’.

view_stages

A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database.

If this field is not set, its default value is [].

Parameters
• field (None) – an optional Field instance describing the type of the list elements

• description (None) – an optional description

• info (None) – an optional info dict

created_at

A datetime field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

last_modified_at

A datetime field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

last_loaded_at

A datetime field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

exception DoesNotExist

Bases: mongoengine.errors.DoesNotExist

args
with_traceback()

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

exception MultipleObjectsReturned

Bases: mongoengine.errors.MultipleObjectsReturned

args
with_traceback()

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

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
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_index(key_or_list, background=False, **kwargs)

Ensure that the given indexes are in place. Deprecated in favour of create_index.

Parameters
• key_or_list – 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

classmethod ensure_indexes()

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

Global defaults can be set in the meta - see 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.

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
classmethod from_json(s)

Loads the document from a JSON string.

Returns
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

id

A field wrapper around MongoDB’s ObjectIds.

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 mongoengine.base.metaclasses.TopLevelDocumentMetaclass Methods:

 get_auto_id_names(new_class) Find a name for the automatic ID field for the given new class. mro Return a type’s method resolution order.
objects(q_obj=None, **query) = []
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(upsert=False, validate=True, clean=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

• clean (True) – whether to call the document’s clean() method. Only applicable when validate is True

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

Returns

self

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, 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

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

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

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.