fiftyone.core.odm#

Module contents#

ODM package declaration.

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

Functions:

`aggregate`(collection, pipelines[, hints, ...])	Executes one or more aggregations on a collection.
`get_db_config`()	Retrieves the database config.
`establish_db_conn`(config)	Establishes the database connection.
`get_db_client`()	Returns a database client.
`get_db_conn`()	Returns a connection to the database.
`get_async_db_client`([use_global])	Returns an async database client.
`get_async_db_conn`([use_global])	Returns an async connection to the database.
`drop_database`()	Drops the database.
`sync_database`()	Syncs all pending database writes to disk.
`list_datasets`()	Returns the list of available FiftyOne datasets.
`patch_saved_views`(dataset_name[, dry_run])	Ensures that the saved view documents in the `views` collection for the given dataset exactly match the IDs in its dataset document.
`patch_annotation_runs`(dataset_name[, dry_run])	Ensures that the annotation runs in the `runs` collection for the given dataset exactly match the values in its dataset document.
`patch_brain_runs`(dataset_name[, dry_run])	Ensures that the brain method runs in the `runs` collection for the given dataset exactly match the values in its dataset document.
`patch_evaluations`(dataset_name[, dry_run])	Ensures that the evaluation runs in the `runs` collection for the given dataset exactly match the values in its dataset document.
`patch_runs`(dataset_name[, dry_run])	Ensures that the runs in the `runs` collection for the given dataset exactly match the values in its dataset document.
`delete_dataset`(name[, dry_run])	Deletes the dataset with the given name.
`delete_saved_view`(dataset_name, view_name[, ...])	Deletes the saved view with the given name from the dataset with the given name.
`delete_saved_views`(dataset_name[, dry_run])	Deletes all saved views from 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.
`delete_run`(name, run_key[, dry_run])	Deletes the run with the given key from the dataset with the given name.
`delete_runs`(name[, dry_run])	Deletes all 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.
`drop_orphan_stores`([dry_run])	Drops all orphan execution stores from the database.
`list_collections`()	Returns a list of all collection names in the database.
`get_collection_stats`(collection_name)	Sets stats about the collection.
`get_indexed_values`(collection, ...[, ...])	Returns the values of the field(s) for all samples in the given collection that are covered by the index.
`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, batcher, ...])	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.
`default_workspace_factory`()	Creates a default top-level instance of `Space`

Classes:

`ActiveFields`(args, *kwargs)	Description of active fields in the App as defined by the sidebar's checkboxes
`SampleFieldDocument`(args, *kwargs)	Description of a sample field.
`ColorScheme`(args, *kwargs)	Description of a color scheme in the App.
`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`(**kwargs)	Backing document for datasets.
`SidebarGroupDocument`(args, *kwargs)	Description of a sidebar group in the App.
`Document`(**kwargs)	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`(**kwargs)
`NoDatasetFrameDocument`(**kwargs)
`RunDocument`(**kwargs)	Backing document for dataset runs.
`DatasetSampleDocument`(**kwargs)	Base class for sample documents backing samples in datasets.
`NoDatasetSampleDocument`(**kwargs)	Backing document for samples that have not been added to a dataset.
`SavedViewDocument`(**kwargs)	Backing document for saved views.
`Panel`(args, *kwargs)	Document for a panel (tab) within a Workspace in the App.
`Space`(args, *kwargs)	Document for configuration of a Space in the App.
`WorkspaceDocument`(args, *kwargs)	Document for configuration of a saved workspace in the App.

Exceptions:

DynamicEmbeddedDocumentException

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

fiftyone.core.odm.aggregate(collection, pipelines, hints=None, maxTimeMS=None, _stream=False)#

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
hints (None) – a corresponding index hint or list of index hints for each pipeline
maxTimeMS (None) – max timeout for the request(s)

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:

config – a fiftyone.core.config.FiftyOneConfig

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(use_global=False)#

Returns an async database client.

Parameters:: use_global – whether to use the global client singleton
Returns:: a motor.motor_asyncio.AsyncIOMotorClient

fiftyone.core.odm.get_async_db_conn(use_global=False)#

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.patch_saved_views(dataset_name, dry_run=False)#

Ensures that the saved view documents in the views collection for the given dataset exactly match the IDs in its dataset document.

Parameters:

dataset_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.patch_annotation_runs(dataset_name, dry_run=False)#

Ensures that the annotation runs in the runs collection for the given dataset exactly match the values in its dataset document.

Parameters:

dataset_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.patch_brain_runs(dataset_name, dry_run=False)#

Ensures that the brain method runs in the runs collection for the given dataset exactly match the values in its dataset document.

Parameters:

dataset_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.patch_evaluations(dataset_name, dry_run=False)#

Ensures that the evaluation runs in the runs collection for the given dataset exactly match the values in its dataset document.

Parameters:

dataset_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.patch_runs(dataset_name, dry_run=False)#

Ensures that the runs in the runs collection for the given dataset exactly match the values in its dataset document.

Parameters:

dataset_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_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_saved_view(dataset_name, view_name, dry_run=False)#

Deletes the saved view with the given name 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.load_saved_view(), which is helpful if a dataset’s backing document or collections are corrupted and cannot be loaded via the normal pathways.

Parameters:

dataset_name – the name of the dataset
view_name – the name of the saved view
dry_run (False) – whether to log the actions that would be taken but not perform them

fiftyone.core.odm.delete_saved_views(dataset_name, dry_run=False)#

Deletes all saved views 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.load_saved_view(), which is helpful if a dataset’s backing document or collections are corrupted and cannot be loaded via the normal pathways.

Parameters:

dataset_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.delete_run(name, run_key, dry_run=False)#

Deletes the 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_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
run_key – the run key
dry_run (False) – whether to log the actions that would be taken but not perform them

fiftyone.core.odm.delete_runs(name, dry_run=False)#

Deletes all 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_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.drop_orphan_stores(dry_run=False)#

Drops all orphan execution stores from the database.

Orphan stores are those that are associated with a dataset that no longer exists in the database.

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

Sets stats about the collection.

Parameters:: collection_name – the name of the collection
Returns:: a stats dict

fiftyone.core.odm.get_indexed_values(collection, field_or_fields, *, index_key=None, query=None, values_only=False, _stream=False)#

Returns the values of the field(s) for all samples in the given collection that are covered by the index. Raises an error if the field is not indexed.

Parameters:

collection – a pymongo.collection.Collection or motor.motor_asyncio.AsyncIOMotorCollection
field_or_fields – the field name or list of field names to retrieve.
index_key (None) – the name of the index to use. If None, the default index name will be constructed from the field name(s).
query (None) – a dict selection filter to apply when querying. For performance, this should only include fields that are in the specified index.
values_only (False) – whether to remove field names from the resulting list. If True, the field names are removed and only the values will be returned as a list for each sample. If False, the field names are preserved and the values will be returned as a dict for each sample.

Returns:

a list of values for the specified field or index keys for each sample sorted in the same order as the index

Raises:

ValueError – if the field is not indexed

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, progress=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)
progress (None) – whether to render a progress bar (True/False), use the default value fiftyone.config.show_progress_bars (None), or a progress callback function to invoke instead

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, batcher=None, progress=None, 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
batcher (None) – an optional fiftyone.core.utils.Batcher class to use to batch the documents, or False to strictly insert the documents in a single batch. By default, fiftyone.config.default_batcher is used
progress (None) – whether to render a progress bar (True/False), use the default value fiftyone.config.show_progress_bars (None), or a progress callback function to invoke instead
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, batcher=None, progress=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
batcher (None) – an optional fiftyone.core.utils.Batcher class to use to batch the operations, or False to strictly perform the operations in a single batch. By default, fiftyone.config.default_batcher is used
progress (False) – whether to render a progress bar (True/False), use the default value fiftyone.config.show_progress_bars (None), or a progress callback function to invoke instead

Returns:

A list of pymongo.results.BulkWriteResult objects

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

Bases: EmbeddedDocument

Description of active fields in the App as defined by the sidebar’s checkboxes

Parameters:

exclude (None) – whether the paths are exclusionary
paths ([]) – the list of field or embedded.field.name paths

Attributes:

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

Methods:

`clean`()	Hook for doing document level data cleaning (usually validation or assignment) before validation is run.
`clear_field`(field_name)	Clears the field from the document.
`copy`()	Returns a deep copy of the document.
`fancy_repr`([class_name, select_fields, ...])	Generates a customizable string representation of the document.
`field_to_mongo`(field_name)
`field_to_python`(field_name, value)
`from_dict`(d[, extended])	Loads the document from a BSON/JSON dictionary.
`from_json`(s)	Loads the document from a JSON string.
`get_field`(field_name)	Gets the field of the document.
`get_text_score`()	Get text score from text query
`has_field`(field_name)	Determines whether the document has a field of the given name.
`iter_fields`()	Returns an iterator over the `(name, value)` pairs of the public fields of the document.
`merge`(doc[, merge_lists, merge_dicts, overwrite])	Merges the contents of the given document into this document.
`set_field`(field_name, value[, create])	Sets the value of a field of the document.
`to_dict`([extended])	Serializes this document to a BSON/JSON dictionary.
`to_json`([pretty_print])	Serializes the document to a JSON string.
`to_mongo`(args, *kwargs)	Return as SON data ready for use with MongoDB.
`validate`([clean])	Ensure that all fields' values are valid and that required fields are present.

Classes:

my_metaclass

alias of DocumentMetaclass

exclude#

A boolean field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

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
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

STRICT = False#

clean()#

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

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

clear_field(field_name)#

Clears the field from the document.

Parameters:: field_name – the field name
Raises:: ValueError – if the field does not exist

copy()#

Returns a deep copy of the document.

Returns:: a SerializableDocument

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

Generates a customizable string representation of the document.

Parameters:

class_name (None) – optional class name to use
select_fields (None) – iterable of field names to restrict to
exclude_fields (None) – iterable of field names to exclude
**kwargs – additional key-value pairs to include in the string representation

Returns:

a string representation of the document

property field_names#: An ordered tuple of the public fields of this document.

field_to_mongo(field_name)#

field_to_python(field_name, value)#

classmethod from_dict(d, extended=False)#

Loads the document from a BSON/JSON dictionary.

Parameters:

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

Returns:

a SerializableDocument

classmethod from_json(s)#

Loads the document from a JSON string.

Returns:: a SerializableDocument

get_field(field_name)#

Gets the field of the document.

Parameters:: field_name – the field name
Returns:: the field value
Raises:: AttributeError – if the field does not exist

get_text_score()#: Get text score from text query

has_field(field_name)#

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

Parameters:: field_name – the field name
Returns:: True/False

iter_fields()#

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

Returns:: an iterator that emits (name, value) tuples

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

Merges the contents of the given document into this document.

Parameters:

doc – a SerializableDocument of same type as this document
merge_lists (True) – whether to merge the elements of top-level list fields rather than treating the list as a single value
merge_dicts (True) – whether to recursively merge the contents of top-level dict fields rather than treating the dict as a single value
overwrite (True) – whether to overwrite (True) or skip (False) existing fields

my_metaclass#: alias of DocumentMetaclass

set_field(field_name, value, create=True)#

Sets the value of a field of the document.

Parameters:

field_name – the field name
value – the field value
create (True) – whether to create the field if it does not exist

Raises:

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

to_dict(extended=False)#

Serializes this document to a BSON/JSON dictionary.

Parameters:: extended (False) – whether to serialize extended JSON constructs such as ObjectIDs, Binary, etc. into JSON format
Returns:: a dict

to_json(pretty_print=False)#

Serializes the document to a JSON string.

Parameters:: pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations
Returns:: a JSON string

to_mongo(*args, **kwargs)#: Return as SON data ready for use with MongoDB.

validate(clean=True)#

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

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

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

Bases: EmbeddedDocument

Description of a sample field.

Attributes:

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

Methods:

`to_field`()	Creates the `fiftyone.core.fields.Field` specified by this document.
`from_field`(field)	Creates a `SampleFieldDocument` for a field.
`clean`()	Hook for doing document level data cleaning (usually validation or assignment) before validation is run.
`clear_field`(field_name)	Clears the field from the document.
`copy`()	Returns a deep copy of the document.
`fancy_repr`([class_name, select_fields, ...])	Generates a customizable string representation of the document.
`field_to_mongo`(field_name)
`field_to_python`(field_name, value)
`from_dict`(d[, extended])	Loads the document from a BSON/JSON dictionary.
`from_json`(s)	Loads the document from a JSON string.
`get_field`(field_name)	Gets the field of the document.
`get_text_score`()	Get text score from text query
`has_field`(field_name)	Determines whether the document has a field of the given name.
`iter_fields`()	Returns an iterator over the `(name, value)` pairs of the public fields of the document.
`merge`(doc[, merge_lists, merge_dicts, overwrite])	Merges the contents of the given document into this document.
`set_field`(field_name, value[, create])	Sets the value of a field of the document.
`to_dict`([extended])	Serializes this document to a BSON/JSON dictionary.
`to_json`([pretty_print])	Serializes the document to a JSON string.
`to_mongo`(args, *kwargs)	Return as SON data ready for use with MongoDB.
`validate`([clean])	Ensure that all fields' values are valid and that required fields are present.

Classes:

my_metaclass

alias of DocumentMetaclass

name#

A unicode string field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

ftype#

A unicode string field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

embedded_doc_type#

A unicode string field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

subfield#

A unicode string field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

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
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

db_field#

A unicode string field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

description#

A unicode string field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

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
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

read_only#

A boolean field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

created_at#

A datetime field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

to_field()#

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

Returns:: a fiftyone.core.fields.Field

classmethod from_field(field)#

Creates a SampleFieldDocument for a field.

Parameters:: field – a fiftyone.core.fields.Field instance
Returns:: a SampleFieldDocument

STRICT = False#

clean()#

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

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

clear_field(field_name)#

Clears the field from the document.

Parameters:: field_name – the field name
Raises:: ValueError – if the field does not exist

copy()#

Returns a deep copy of the document.

Returns:: a SerializableDocument

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

Generates a customizable string representation of the document.

Parameters:

class_name (None) – optional class name to use
select_fields (None) – iterable of field names to restrict to
exclude_fields (None) – iterable of field names to exclude
**kwargs – additional key-value pairs to include in the string representation

Returns:

a string representation of the document

property field_names#: An ordered tuple of the public fields of this document.

field_to_mongo(field_name)#

field_to_python(field_name, value)#

classmethod from_dict(d, extended=False)#

Loads the document from a BSON/JSON dictionary.

Parameters:

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

Returns:

a SerializableDocument

classmethod from_json(s)#

Loads the document from a JSON string.

Returns:: a SerializableDocument

get_field(field_name)#

Gets the field of the document.

Parameters:: field_name – the field name
Returns:: the field value
Raises:: AttributeError – if the field does not exist

get_text_score()#: Get text score from text query

has_field(field_name)#

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

Parameters:: field_name – the field name
Returns:: True/False

iter_fields()#

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

Returns:: an iterator that emits (name, value) tuples

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

Merges the contents of the given document into this document.

Parameters:

doc – a SerializableDocument of same type as this document
merge_lists (True) – whether to merge the elements of top-level list fields rather than treating the list as a single value
merge_dicts (True) – whether to recursively merge the contents of top-level dict fields rather than treating the dict as a single value
overwrite (True) – whether to overwrite (True) or skip (False) existing fields

my_metaclass#: alias of DocumentMetaclass

set_field(field_name, value, create=True)#

Sets the value of a field of the document.

Parameters:

field_name – the field name
value – the field value
create (True) – whether to create the field if it does not exist

Raises:

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

to_dict(extended=False)#

Serializes this document to a BSON/JSON dictionary.

Parameters:: extended (False) – whether to serialize extended JSON constructs such as ObjectIDs, Binary, etc. into JSON format
Returns:: a dict

to_json(pretty_print=False)#

Serializes the document to a JSON string.

Parameters:: pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations
Returns:: a JSON string

to_mongo(*args, **kwargs)#: Return as SON data ready for use with MongoDB.

validate(clean=True)#

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

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

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

Bases: EmbeddedDocument

Description of a color scheme in the App.

Example:

import fiftyone as fo
import fiftyone.zoo as foz

dataset = foz.load_zoo_dataset("quickstart")

# Store a custom color scheme for a dataset
dataset.app_config.color_scheme = fo.ColorScheme(
    color_by="value",
    color_pool=[
        "#ff0000",
        "#00ff00",
        "#0000ff",
        "pink",
        "yellowgreen",
    ],
    fields=[
        {
            "path": "ground_truth",
            "fieldColor": "#ff00ff",
            "colorByAttribute": "label",
            "valueColors": [{"value": "dog", "color": "yellow"}],
            "maskTargetsColors": [
                {"intTarget": 2, "color": "#ff0000"},
                {"intTarget": 12, "color": "#99ff00"},
            ],
        }
    ],
    label_tags={
        "fieldColor": "#00ffff",
        "valueColors": [
            {"value": "correct", "color": "#ff00ff"},
            {"value": "mistake", "color": "#00ff00"},
        ],
    },
    colorscales=[
        {
            "path": "heatmap1",
            "list": [
                {"value": 0, "color": "rgb(0, 0, 255)"},
                {"value": 1, "color": "rgb(0, 255, 255)"},
            ],
        },
        {
            "path": "heatmap2",
            "name": "hsv",
        },
    ],
    multicolor_keypoints=False,
    opacity=0.5,
    show_skeletons=True,
    default_mask_targets_colors=[
        {"intTarget": 1, "color": "#FEC0AA"},
        {"intTarget": 2, "color": "#EC4E20"},
    ],
    default_colorscale={"name": "sunset", "list": None},
)

session = fo.launch_app(dataset)

Parameters:

color_by (None) – whether annotations should be colored by "field", "value", or "instance"
color_pool (None) – an optional list of colors to use as a color pool for this dataset
multicolor_keypoints (None) – whether to use multiple colors for keypoints
opacity (None) – transparency of the annotation, between 0 and 1
show_skeletons (None) – whether to show skeletons of keypoints
fields (None) –
an optional list of dicts of per-field custom colors with the following keys:
- path (required): the fully-qualified path to the field you’re customizing
- fieldColor (optional): a color to assign to the field in the App sidebar
- colorByAttribute (optional): the attribute to use to assign per-value colors. Only applicable when the field is an embedded document
- valueColors (optional): a list of dicts specifying colors to use for individual values of this field
- maskTargetsColors (optional): a list of dicts specifying index and color for 2D masks in the same format as described below for default mask targets
default_mask_targets_colors (None) –
a list of dicts with the following keys specifying index and color for 2D masks of the dataset. If a field does not have field specific mask targets colors, this list will be used:
- intTarget: an integer target value
- color: a color string
Note that the pixel value 0 is a reserved “background” class that is always rendered as invisible in the App
default_colorscale (None) –
dataset default colorscale dict with the following keys:
- name (optional): a named plotly colorscale, e.g. "hsv". See https://plotly.com/python/builtin-colorscales
- list (optional): a list of dicts of colorscale values
  - value: a float number between 0 and 1. A valid list must have have colors defined for 0 and 1
  - color: an RGB color string
colorscales (None) –
an optional list of dicts of per-field custom colorscales with the following keys:
- path (required): the fully-qualified path to the field you’re customizing. use “dataset” if you are setting the default colorscale for dataset
- name (optional): a named colorscale plotly recognizes
- list (optional): a list of dicts of colorscale values with the following keys:
  - value: a float number between 0 and 1. A valid list must have have colors defined for 0 and 1
  - color: an RGB color string
label_tags (None) –
an optional dict specifying custom colors for label tags with the following keys:
- fieldColor (optional): a color to assign to all label tags
- valueColors (optional): a list of dicts

Attributes:

`id`	An Object ID field.
`color_pool`	A list field that wraps a standard `Field`, allowing multiple instances of the field to be stored as a list in the database.
`color_by`	A unicode string field.
`fields`	A list field that wraps a standard `Field`, allowing multiple instances of the field to be stored as a list in the database.
`label_tags`	A dictionary field that wraps a standard Python dictionary.
`multicolor_keypoints`	A boolean field.
`opacity`	A floating point number field.
`show_skeletons`	A boolean field.
`default_mask_targets_colors`	A list field that wraps a standard `Field`, allowing multiple instances of the field to be stored as a list in the database.
`colorscales`	A list field that wraps a standard `Field`, allowing multiple instances of the field to be stored as a list in the database.
`default_colorscale`	A dictionary field that wraps a standard Python dictionary.
`STRICT`
`field_names`	An ordered tuple of the public fields of this document.

Methods:

`clean`()	Hook for doing document level data cleaning (usually validation or assignment) before validation is run.
`clear_field`(field_name)	Clears the field from the document.
`copy`()	Returns a deep copy of the document.
`fancy_repr`([class_name, select_fields, ...])	Generates a customizable string representation of the document.
`field_to_mongo`(field_name)
`field_to_python`(field_name, value)
`from_dict`(d[, extended])	Loads the document from a BSON/JSON dictionary.
`from_json`(s)	Loads the document from a JSON string.
`get_field`(field_name)	Gets the field of the document.
`get_text_score`()	Get text score from text query
`has_field`(field_name)	Determines whether the document has a field of the given name.
`iter_fields`()	Returns an iterator over the `(name, value)` pairs of the public fields of the document.
`merge`(doc[, merge_lists, merge_dicts, overwrite])	Merges the contents of the given document into this document.
`set_field`(field_name, value[, create])	Sets the value of a field of the document.
`to_dict`([extended])	Serializes this document to a BSON/JSON dictionary.
`to_json`([pretty_print])	Serializes the document to a JSON string.
`to_mongo`(args, *kwargs)	Return as SON data ready for use with MongoDB.
`validate`([clean])	Ensure that all fields' values are valid and that required fields are present.

Classes:

my_metaclass

alias of DocumentMetaclass

id#

An Object ID field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

color_pool#

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
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

color_by#

A unicode string field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

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
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

label_tags#

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
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

multicolor_keypoints#

A boolean field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

opacity#

A floating point number field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

show_skeletons#

A boolean field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

default_mask_targets_colors#

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
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

colorscales#

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
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

default_colorscale#

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
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

STRICT = False#

clean()#

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

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

clear_field(field_name)#

Clears the field from the document.

Parameters:: field_name – the field name
Raises:: ValueError – if the field does not exist

copy()#

Returns a deep copy of the document.

Returns:: a SerializableDocument

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

Generates a customizable string representation of the document.

Parameters:

class_name (None) – optional class name to use
select_fields (None) – iterable of field names to restrict to
exclude_fields (None) – iterable of field names to exclude
**kwargs – additional key-value pairs to include in the string representation

Returns:

a string representation of the document

property field_names#: An ordered tuple of the public fields of this document.

field_to_mongo(field_name)#

field_to_python(field_name, value)#

classmethod from_dict(d, extended=False)#

Loads the document from a BSON/JSON dictionary.

Parameters:

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

Returns:

a SerializableDocument

classmethod from_json(s)#

Loads the document from a JSON string.

Returns:: a SerializableDocument

get_field(field_name)#

Gets the field of the document.

Parameters:: field_name – the field name
Returns:: the field value
Raises:: AttributeError – if the field does not exist

get_text_score()#: Get text score from text query

has_field(field_name)#

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

Parameters:: field_name – the field name
Returns:: True/False

iter_fields()#

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

Returns:: an iterator that emits (name, value) tuples

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

Merges the contents of the given document into this document.

Parameters:

doc – a SerializableDocument of same type as this document
merge_lists (True) – whether to merge the elements of top-level list fields rather than treating the list as a single value
merge_dicts (True) – whether to recursively merge the contents of top-level dict fields rather than treating the dict as a single value
overwrite (True) – whether to overwrite (True) or skip (False) existing fields

my_metaclass#: alias of DocumentMetaclass

set_field(field_name, value, create=True)#

Sets the value of a field of the document.

Parameters:

field_name – the field name
value – the field value
create (True) – whether to create the field if it does not exist

Raises:

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

to_dict(extended=False)#

Serializes this document to a BSON/JSON dictionary.

Parameters:: extended (False) – whether to serialize extended JSON constructs such as ObjectIDs, Binary, etc. into JSON format
Returns:: a dict

to_json(pretty_print=False)#

Serializes the document to a JSON string.

Parameters:: pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations
Returns:: a JSON string

to_mongo(*args, **kwargs)#: Return as SON data ready for use with MongoDB.

validate(clean=True)#

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

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

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

Bases: EmbeddedDocument

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:

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

Methods:

`clean`()	Hook for doing document level data cleaning (usually validation or assignment) before validation is run.
`clear_field`(field_name)	Clears the field from the document.
`copy`()	Returns a deep copy of the document.
`fancy_repr`([class_name, select_fields, ...])	Generates a customizable string representation of the document.
`field_to_mongo`(field_name)
`field_to_python`(field_name, value)
`from_dict`(d[, extended])	Loads the document from a BSON/JSON dictionary.
`from_json`(s)	Loads the document from a JSON string.
`get_field`(field_name)	Gets the field of the document.
`get_text_score`()	Get text score from text query
`has_field`(field_name)	Determines whether the document has a field of the given name.
`iter_fields`()	Returns an iterator over the `(name, value)` pairs of the public fields of the document.
`merge`(doc[, merge_lists, merge_dicts, overwrite])	Merges the contents of the given document into this document.
`set_field`(field_name, value[, create])	Sets the value of a field of the document.
`to_dict`([extended])	Serializes this document to a BSON/JSON dictionary.
`to_json`([pretty_print])	Serializes the document to a JSON string.
`to_mongo`(args, *kwargs)	Return as SON data ready for use with MongoDB.
`validate`([clean])	Ensure that all fields' values are valid and that required fields are present.

Classes:

my_metaclass

alias of DocumentMetaclass

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
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

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
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

STRICT = False#

clean()#

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

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

clear_field(field_name)#

Clears the field from the document.

Parameters:: field_name – the field name
Raises:: ValueError – if the field does not exist

copy()#

Returns a deep copy of the document.

Returns:: a SerializableDocument

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

Generates a customizable string representation of the document.

Parameters:

class_name (None) – optional class name to use
select_fields (None) – iterable of field names to restrict to
exclude_fields (None) – iterable of field names to exclude
**kwargs – additional key-value pairs to include in the string representation

Returns:

a string representation of the document

property field_names#: An ordered tuple of the public fields of this document.

field_to_mongo(field_name)#

field_to_python(field_name, value)#

classmethod from_dict(d, extended=False)#

Loads the document from a BSON/JSON dictionary.

Parameters:

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

Returns:

a SerializableDocument

classmethod from_json(s)#

Loads the document from a JSON string.

Returns:: a SerializableDocument

get_field(field_name)#

Gets the field of the document.

Parameters:: field_name – the field name
Returns:: the field value
Raises:: AttributeError – if the field does not exist

get_text_score()#: Get text score from text query

has_field(field_name)#

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

Parameters:: field_name – the field name
Returns:: True/False

iter_fields()#

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

Returns:: an iterator that emits (name, value) tuples

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

Merges the contents of the given document into this document.

Parameters:

doc – a SerializableDocument of same type as this document
merge_lists (True) – whether to merge the elements of top-level list fields rather than treating the list as a single value
merge_dicts (True) – whether to recursively merge the contents of top-level dict fields rather than treating the dict as a single value
overwrite (True) – whether to overwrite (True) or skip (False) existing fields

my_metaclass#: alias of DocumentMetaclass

set_field(field_name, value, create=True)#

Sets the value of a field of the document.

Parameters:

field_name – the field name
value – the field value
create (True) – whether to create the field if it does not exist

Raises:

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

to_dict(extended=False)#

Serializes this document to a BSON/JSON dictionary.

Parameters:: extended (False) – whether to serialize extended JSON constructs such as ObjectIDs, Binary, etc. into JSON format
Returns:: a dict

to_json(pretty_print=False)#

Serializes the document to a JSON string.

Parameters:: pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations
Returns:: a JSON string

to_mongo(*args, **kwargs)#: Return as SON data ready for use with MongoDB.

validate(clean=True)#

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

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

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

Bases: EmbeddedDocument

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

Parameters:

active_fields (None) – an optional ActiveFields dataset default
color_scheme (None) – an optional ColorScheme dataset default
disable_frame_filtering (False) – whether to disable frame filtering for video datasets in the App’s grid view
dynamic_groups_target_frame_rate (30) – the target frame rate when rendering ordered dynamic groups of images as videos
grid_media_field ("filepath") – the default sample field from which to serve media in the App’s grid view
media_fallback (False) – whether to fall back to the default media field ("filepath") when the alternate media field value for a sample is not defined
media_fields (["filepath"]) – the list of sample fields that contain media and should be available to choose from the App’s settings menus
modal_media_field ("filepath") – the default sample field from which to serve media in the App’s modal view
plugins ({}) –
an optional dict mapping plugin names to plugin configuration dicts. Builtin plugins include:
- "map": See the map plugin docs for supported options
- "point-cloud": See the 3D visualizer docs for supported options
sidebar_groups (None) – an optional list of SidebarGroupDocument describing sidebar groups to use in the App

Attributes:

`active_fields`	A field that stores instances of a given type of `fiftyone.core.odm.BaseEmbeddedDocument` object.
`color_scheme`	A field that stores instances of a given type of `fiftyone.core.odm.BaseEmbeddedDocument` object.
`disable_frame_filtering`	A boolean field.
`dynamic_groups_target_frame_rate`	A 32 bit integer field.
`grid_media_field`	A unicode string field.
`media_fallback`	A boolean 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.
`STRICT`
`field_names`	An ordered tuple of the public fields of this document.

Methods:

`default_active_fields`(sample_collection)	Generates the default `active_fields` for the given collection.
`default_sidebar_groups`(sample_collection)	Generates the default `sidebar_groups` for the given collection.
`is_custom`()	Determines whether this app config differs from the default one.
`clean`()	Hook for doing document level data cleaning (usually validation or assignment) before validation is run.
`clear_field`(field_name)	Clears the field from the document.
`copy`()	Returns a deep copy of the document.
`fancy_repr`([class_name, select_fields, ...])	Generates a customizable string representation of the document.
`field_to_mongo`(field_name)
`field_to_python`(field_name, value)
`from_dict`(d[, extended])	Loads the document from a BSON/JSON dictionary.
`from_json`(s)	Loads the document from a JSON string.
`get_field`(field_name)	Gets the field of the document.
`get_text_score`()	Get text score from text query
`has_field`(field_name)	Determines whether the document has a field of the given name.
`iter_fields`()	Returns an iterator over the `(name, value)` pairs of the public fields of the document.
`merge`(doc[, merge_lists, merge_dicts, overwrite])	Merges the contents of the given document into this document.
`set_field`(field_name, value[, create])	Sets the value of a field of the document.
`to_dict`([extended])	Serializes this document to a BSON/JSON dictionary.
`to_json`([pretty_print])	Serializes the document to a JSON string.
`to_mongo`(args, *kwargs)	Return as SON data ready for use with MongoDB.
`validate`([clean])	Ensure that all fields' values are valid and that required fields are present.

Classes:

my_metaclass

alias of DocumentMetaclass

active_fields#

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

Parameters:

document_type – the fiftyone.core.odm.BaseEmbeddedDocument type stored in this field
description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

color_scheme#

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

Parameters:

document_type – the fiftyone.core.odm.BaseEmbeddedDocument type stored in this field
description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

disable_frame_filtering#

A boolean field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

dynamic_groups_target_frame_rate#

A 32 bit integer field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

grid_media_field#

A unicode string field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

media_fallback#

A boolean field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

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
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

modal_media_field#

A unicode string field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

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
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

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
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

static default_active_fields(sample_collection)#

Generates the default active_fields for the given collection.

Examples:

import fiftyone as fo
import fiftyone.zoo as foz

dataset = foz.load_zoo_dataset("quickstart")

active_fields = fo.DatasetAppConfig.default_active_fields(dataset)
dataset.app_config.active_fields = active_fields
print(dataset.app_config)

Parameters:: sample_collection – a fiftyone.core.collections.SampleCollection
Returns:: an ActiveFields instance

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

dataset = foz.load_zoo_dataset("quickstart")

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:: a SerializableDocument

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

Generates a customizable string representation of the document.

Parameters:

class_name (None) – optional class name to use
select_fields (None) – iterable of field names to restrict to
exclude_fields (None) – iterable of field names to exclude
**kwargs – additional key-value pairs to include in the string representation

Returns:

a string representation of the document

property field_names#: An ordered tuple of the public fields of this document.

field_to_mongo(field_name)#

field_to_python(field_name, value)#

classmethod from_dict(d, extended=False)#

Loads the document from a BSON/JSON dictionary.

Parameters:

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

Returns:

a SerializableDocument

classmethod from_json(s)#

Loads the document from a JSON string.

Returns:: a SerializableDocument

get_field(field_name)#

Gets the field of the document.

Parameters:: field_name – the field name
Returns:: the field value
Raises:: AttributeError – if the field does not exist

get_text_score()#: Get text score from text query

has_field(field_name)#

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

Parameters:: field_name – the field name
Returns:: True/False

iter_fields()#

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

Returns:: an iterator that emits (name, value) tuples

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

Merges the contents of the given document into this document.

Parameters:

doc – a SerializableDocument of same type as this document
merge_lists (True) – whether to merge the elements of top-level list fields rather than treating the list as a single value
merge_dicts (True) – whether to recursively merge the contents of top-level dict fields rather than treating the dict as a single value
overwrite (True) – whether to overwrite (True) or skip (False) existing fields

my_metaclass#: alias of DocumentMetaclass

set_field(field_name, value, create=True)#

Sets the value of a field of the document.

Parameters:

field_name – the field name
value – the field value
create (True) – whether to create the field if it does not exist

Raises:

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

to_dict(extended=False)#

Serializes this document to a BSON/JSON dictionary.

Parameters:: extended (False) – whether to serialize extended JSON constructs such as ObjectIDs, Binary, etc. into JSON format
Returns:: a dict

to_json(pretty_print=False)#

Serializes the document to a JSON string.

Parameters:: pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations
Returns:: a JSON string

to_mongo(*args, **kwargs)#: Return as SON data ready for use with MongoDB.

validate(clean=True)#

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

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

class fiftyone.core.odm.DatasetDocument(**kwargs)#

Bases: Document

Backing document for datasets.

Attributes:

`name`	A unicode string field.
`slug`	A unicode string field.
`version`	A unicode string field.
`created_at`	A datetime field.
`last_modified_at`	A datetime field.
`last_deletion_at`	A datetime field.
`last_loaded_at`	A datetime field.
`sample_collection_name`	A unicode string field.
`frame_collection_name`	A unicode string field.
`persistent`	A boolean field.
`media_type`	A unicode string field.
`group_field`	A unicode string field.
`group_media_types`	A dictionary field that wraps a standard Python dictionary.
`default_group_slice`	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.
`description`	A unicode string field.
`info`	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.
`classes`	A dictionary field that wraps a standard Python dictionary.
`default_classes`	A `ListField` that stores class label strings.
`mask_targets`	A dictionary field that wraps a standard Python dictionary.
`default_mask_targets`	A `DictField` that stores mapping between integer keys or RGB string hex keys and string targets.
`skeletons`	A dictionary field that wraps a standard Python dictionary.
`default_skeleton`	A field that stores instances of a given type of `fiftyone.core.odm.BaseEmbeddedDocument` object.
`sample_fields`	A field that stores a list of a given type of `fiftyone.core.odm.BaseEmbeddedDocument` objects.
`frame_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.
`workspaces`	A list field that wraps a standard `Field`, allowing multiple instances of the field to be stored as a list in the database.
`annotation_runs`	A dictionary field that wraps a standard Python dictionary.
`brain_methods`	A dictionary field that wraps a standard Python dictionary.
`evaluations`	A dictionary field that wraps a standard Python dictionary.
`runs`	A dictionary field that wraps a standard Python dictionary.
`STRICT`
`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.
`pk`	Get the primary key.

Methods:

`get_saved_views`()
`get_workspaces`()
`get_annotation_runs`()
`get_brain_methods`()
`get_evaluations`()
`get_runs`()
`cascade_save`(**kwargs)	Recursively save any references and generic references on the document.
`clean`()	Hook for doing document level data cleaning (usually validation or assignment) before validation is run.
`clear_field`(field_name)	Clears the field from the document.
`compare_indexes`()	Compares the indexes defined in MongoEngine with the ones existing in the database.
`copy`([new_id])	Returns a deep copy of the document.
`copy_with_new_id`()
`create_index`(keys[, background])	Creates the given indexes if required.
`delete`([signal_kwargs])	Delete the `Document` from the database.
`drop_collection`()	Drops the entire collection associated with this `Document` type from the database.
`ensure_indexes`()	Checks the document meta data and ensures all the indexes exist.
`fancy_repr`([class_name, select_fields, ...])	Generates a customizable string representation of the document.
`field_to_mongo`(field_name)
`field_to_python`(field_name, value)
`from_dict`(d[, extended])	Loads the document from a BSON/JSON dictionary.
`from_json`(s)	Loads the document from a JSON string.
`get_field`(field_name)	Gets the field of the document.
`get_text_score`()	Get text score from text query
`has_field`(field_name)	Determines whether the document has a field of the given name.
`iter_fields`()	Returns an iterator over the `(name, value)` pairs of the public fields of the document.
`list_indexes`()	Lists all indexes that should be created for the Document collection.
`merge`(doc[, merge_lists, merge_dicts, overwrite])	Merges the contents of the given document into this document.
`modify`([query])	Perform an atomic update of the document in the database and reload the document object using updated version.
`register_delete_rule`(document_cls, ...)	This method registers the delete rules to apply when removing this object.
`reload`(fields, *kwargs)	Reloads the document from the database.
`save`([upsert, validate, 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.
`to_dbref`()	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.

Miscellaneous:

`DoesNotExist`
`MultipleObjectsReturned`

Classes:

my_metaclass

alias of TopLevelDocumentMetaclass

name#

A unicode string field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

slug#

A unicode string field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

version#

A unicode string field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

created_at#

A datetime field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

last_modified_at#

A datetime field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

last_deletion_at#

A datetime field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

last_loaded_at#

A datetime field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

sample_collection_name#

A unicode string field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

frame_collection_name#

A unicode string field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

persistent#

A boolean field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

media_type#

A unicode string field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

group_field#

A unicode string field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

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
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

default_group_slice#

A unicode string field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

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
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

description#

A unicode string field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

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
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

app_config#

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

Parameters:

document_type – the fiftyone.core.odm.BaseEmbeddedDocument type stored in this field
description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

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
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

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
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

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
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

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
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

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
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

default_skeleton#

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

Parameters:

document_type – the fiftyone.core.odm.BaseEmbeddedDocument type stored in this field
description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

sample_fields#

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

Parameters:

document_type – the fiftyone.core.odm.BaseEmbeddedDocument type stored in this field
description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

frame_fields#

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

Parameters:

document_type – the fiftyone.core.odm.BaseEmbeddedDocument type stored in this field
description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

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
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

workspaces#

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
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

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
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

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
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

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
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

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
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

get_saved_views()#

get_workspaces()#

get_annotation_runs()#

get_brain_methods()#

get_evaluations()#

get_runs()#

exception DoesNotExist#

Bases: DoesNotExist

Methods:

`add_note`	Exception.add_note(note) -- add a note to the exception
`with_traceback`	Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

Attributes:

args

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

args#

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

exception MultipleObjectsReturned#

Bases: MultipleObjectsReturned

Methods:

`add_note`	Exception.add_note(note) -- add a note to the exception
`with_traceback`	Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

Attributes:

args

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

args#

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

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(new_id=False)#

Returns a deep copy of the document.

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

copy_with_new_id()#

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

Creates the given indexes if required.

Parameters:

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

delete(signal_kwargs=None, **write_concern)#

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

Parameters:

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

classmethod drop_collection()#

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

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

classmethod ensure_indexes()#

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

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

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

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

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

Note

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

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

Generates a customizable string representation of the document.

Parameters:

class_name (None) – optional class name to use
select_fields (None) – iterable of field names to restrict to
exclude_fields (None) – iterable of field names to exclude
**kwargs – additional key-value pairs to include in the string representation

Returns:

a string representation of the document

property field_names#: An ordered tuple of the public fields of this document.

field_to_mongo(field_name)#

field_to_python(field_name, value)#

classmethod from_dict(d, extended=False)#

Loads the document from a BSON/JSON dictionary.

Parameters:

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

Returns:

a SerializableDocument

classmethod from_json(s)#

Loads the document from a JSON string.

Returns:: a SerializableDocument

get_field(field_name)#

Gets the field of the document.

Parameters:: field_name – the field name
Returns:: the field value
Raises:: AttributeError – if the field does not exist

get_text_score()#: Get text score from text query

has_field(field_name)#

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

Parameters:: field_name – the field name
Returns:: True/False

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 TopLevelDocumentMetaclass

property pk#: Get the primary key.

classmethod register_delete_rule(document_cls, field_name, rule)#: This method registers the delete rules to apply when removing this object.

reload(*fields, **kwargs)#

Reloads the document from the database.

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

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

Saves the document to the database.

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

Parameters:

upsert (False) – whether to insert the document if it has an id populated but no document with that ID exists in the database
validate (True) – whether to validate the document
safe (False) – whether to reload() the document before raising any errors

Returns:

self

select_related(max_depth=1)#: Handles dereferencing of DBRef objects to a maximum depth in order to cut down the number queries to mongodb.

set_field(field_name, value, create=True)#

Sets the value of a field of the document.

Parameters:

field_name – the field name
value – the field value
create (True) – whether to create the field if it does not exist

Raises:

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

switch_collection(collection_name, keep_created=True)#

Temporarily switch the collection for a document instance.

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

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

Parameters:

collection_name (str) – The database alias to use for saving the document
keep_created (bool) – keep self._created value after switching collection, else is reset to True

See also

Use switch_db if you need to read from another database

switch_db(db_alias, keep_created=True)#

Temporarily switch the database for a document instance.

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

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

Parameters:

db_alias (str) – The database alias to use for saving the document
keep_created (bool) – keep self._created value after switching db, else is reset to True

See also

Use switch_collection if you need to read from another collection

to_dbref()#: Returns an instance of DBRef useful in __raw__ queries.

to_dict(*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

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

Bases: EmbeddedDocument

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:

`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.
`expanded`	A boolean field.
`STRICT`
`field_names`	An ordered tuple of the public fields of this document.

Methods:

`clean`()	Hook for doing document level data cleaning (usually validation or assignment) before validation is run.
`clear_field`(field_name)	Clears the field from the document.
`copy`()	Returns a deep copy of the document.
`fancy_repr`([class_name, select_fields, ...])	Generates a customizable string representation of the document.
`field_to_mongo`(field_name)
`field_to_python`(field_name, value)
`from_dict`(d[, extended])	Loads the document from a BSON/JSON dictionary.
`from_json`(s)	Loads the document from a JSON string.
`get_field`(field_name)	Gets the field of the document.
`get_text_score`()	Get text score from text query
`has_field`(field_name)	Determines whether the document has a field of the given name.
`iter_fields`()	Returns an iterator over the `(name, value)` pairs of the public fields of the document.
`merge`(doc[, merge_lists, merge_dicts, overwrite])	Merges the contents of the given document into this document.
`set_field`(field_name, value[, create])	Sets the value of a field of the document.
`to_dict`([extended])	Serializes this document to a BSON/JSON dictionary.
`to_json`([pretty_print])	Serializes the document to a JSON string.
`to_mongo`(args, *kwargs)	Return as SON data ready for use with MongoDB.
`validate`([clean])	Ensure that all fields' values are valid and that required fields are present.

Classes:

my_metaclass

alias of DocumentMetaclass

name#

A unicode string field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

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
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

expanded#

A boolean field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

STRICT = False#

clean()#

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

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

clear_field(field_name)#

Clears the field from the document.

Parameters:: field_name – the field name
Raises:: ValueError – if the field does not exist

copy()#

Returns a deep copy of the document.

Returns:: a SerializableDocument

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

Generates a customizable string representation of the document.

Parameters:

class_name (None) – optional class name to use
select_fields (None) – iterable of field names to restrict to
exclude_fields (None) – iterable of field names to exclude
**kwargs – additional key-value pairs to include in the string representation

Returns:

a string representation of the document

property field_names#: An ordered tuple of the public fields of this document.

field_to_mongo(field_name)#

field_to_python(field_name, value)#

classmethod from_dict(d, extended=False)#

Loads the document from a BSON/JSON dictionary.

Parameters:

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

Returns:

a SerializableDocument

classmethod from_json(s)#

Loads the document from a JSON string.

Returns:: a SerializableDocument

get_field(field_name)#

Gets the field of the document.

Parameters:: field_name – the field name
Returns:: the field value
Raises:: AttributeError – if the field does not exist

get_text_score()#: Get text score from text query

has_field(field_name)#

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

Parameters:: field_name – the field name
Returns:: True/False

iter_fields()#

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

Returns:: an iterator that emits (name, value) tuples

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

Merges the contents of the given document into this document.

Parameters:

doc – a SerializableDocument of same type as this document
merge_lists (True) – whether to merge the elements of top-level list fields rather than treating the list as a single value
merge_dicts (True) – whether to recursively merge the contents of top-level dict fields rather than treating the dict as a single value
overwrite (True) – whether to overwrite (True) or skip (False) existing fields

my_metaclass#: alias of DocumentMetaclass

set_field(field_name, value, create=True)#

Sets the value of a field of the document.

Parameters:

field_name – the field name
value – the field value
create (True) – whether to create the field if it does not exist

Raises:

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

to_dict(extended=False)#

Serializes this document to a BSON/JSON dictionary.

Parameters:: extended (False) – whether to serialize extended JSON constructs such as ObjectIDs, Binary, etc. into JSON format
Returns:: a dict

to_json(pretty_print=False)#

Serializes the document to a JSON string.

Parameters:: pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations
Returns:: a JSON string

to_mongo(*args, **kwargs)#: Return as SON data ready for use with MongoDB.

validate(clean=True)#

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

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

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

Bases: BaseDocument, Document

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

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

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

Methods:

`copy`([new_id])	Returns a deep copy of the document.
`reload`(fields, *kwargs)	Reloads the document from the database.
`save`([upsert, validate, safe])	Saves the document to the database.
`copy_with_new_id`()
`cascade_save`(**kwargs)	Recursively save any references and generic references on the document.
`clean`()	Hook for doing document level data cleaning (usually validation or assignment) before validation is run.
`clear_field`(field_name)	Clears the field from the document.
`compare_indexes`()	Compares the indexes defined in MongoEngine with the ones existing in the database.
`create_index`(keys[, background])	Creates the given indexes if required.
`delete`([signal_kwargs])	Delete the `Document` from the database.
`drop_collection`()	Drops the entire collection associated with this `Document` type from the database.
`ensure_indexes`()	Checks the document meta data and ensures all the indexes exist.
`fancy_repr`([class_name, select_fields, ...])	Generates a customizable string representation of the document.
`field_to_mongo`(field_name)
`field_to_python`(field_name, value)
`from_dict`(d[, extended])	Loads the document from a BSON/JSON dictionary.
`from_json`(s)	Loads the document from a JSON string.
`get_field`(field_name)	Gets the field of the document.
`get_text_score`()	Get text score from text query
`has_field`(field_name)	Determines whether the document has a field of the given name.
`iter_fields`()	Returns an iterator over the `(name, value)` pairs of the public fields of the document.
`list_indexes`()	Lists all indexes that should be created for the Document collection.
`merge`(doc[, merge_lists, merge_dicts, overwrite])	Merges the contents of the given document into this document.
`modify`([query])	Perform an atomic update of the document in the database and reload the document object using updated version.
`register_delete_rule`(document_cls, ...)	This method registers the delete rules to apply when removing this object.
`select_related`([max_depth])	Handles dereferencing of `DBRef` objects to a maximum depth in order to cut down the number queries to mongodb.
`set_field`(field_name, value[, create])	Sets the value of a field of the document.
`switch_collection`(collection_name[, ...])	Temporarily switch the collection for a document instance.
`switch_db`(db_alias[, keep_created])	Temporarily switch the database for a document instance.
`to_dbref`()	Returns an instance of `DBRef` useful in __raw__ queries.
`to_dict`([extended])	Serializes this document to a BSON/JSON dictionary.
`to_json`([pretty_print])	Serializes the document to a JSON string.
`to_mongo`(args, *kwargs)	Return as SON data ready for use with MongoDB.
`update`(**kwargs)	Performs an update on the `Document` A convenience wrapper to `update()`.
`validate`([clean])	Ensure that all fields' values are valid and that required fields are present.

Attributes:

`STRICT`
`field_names`	An ordered tuple of the public fields of this document.
`in_db`	Whether the document has been inserted into the database.
`pk`	Get the primary key.

Classes:

my_metaclass

alias of TopLevelDocumentMetaclass

copy(new_id=False)#

Returns a deep copy of the document.

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

reload(*fields, **kwargs)#

Reloads the document from the database.

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

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

Saves the document to the database.

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

Parameters:

upsert (False) – whether to insert the document if it has an id populated but no document with that ID exists in the database
validate (True) – whether to validate the document
safe (False) – whether to reload() the document before raising any errors

Returns:

self

copy_with_new_id()#

STRICT = False#

cascade_save(**kwargs)#: Recursively save any references and generic references on the document.

clean()#

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

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

clear_field(field_name)#

Clears the field from the document.

Parameters:: field_name – the field name
Raises:: ValueError – if the field does not exist

classmethod compare_indexes()#: Compares the indexes defined in MongoEngine with the ones existing in the database. Returns any missing/extra indexes.

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

Creates the given indexes if required.

Parameters:

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

delete(signal_kwargs=None, **write_concern)#

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

Parameters:

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

classmethod drop_collection()#

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

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

classmethod ensure_indexes()#

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

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

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

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

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

Note

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

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

Generates a customizable string representation of the document.

Parameters:

class_name (None) – optional class name to use
select_fields (None) – iterable of field names to restrict to
exclude_fields (None) – iterable of field names to exclude
**kwargs – additional key-value pairs to include in the string representation

Returns:

a string representation of the document

property field_names#: An ordered tuple of the public fields of this document.

field_to_mongo(field_name)#

field_to_python(field_name, value)#

classmethod from_dict(d, extended=False)#

Loads the document from a BSON/JSON dictionary.

Parameters:

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

Returns:

a SerializableDocument

classmethod from_json(s)#

Loads the document from a JSON string.

Returns:: a SerializableDocument

get_field(field_name)#

Gets the field of the document.

Parameters:: field_name – the field name
Returns:: the field value
Raises:: AttributeError – if the field does not exist

get_text_score()#: Get text score from text query

has_field(field_name)#

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

Parameters:: field_name – the field name
Returns:: True/False

property in_db#: Whether the document has been inserted into the database.

iter_fields()#

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

Returns:: an iterator that emits (name, value) tuples

classmethod list_indexes()#

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

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

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

Merges the contents of the given document into this document.

Parameters:

doc – a SerializableDocument of same type as this document
merge_lists (True) – whether to merge the elements of top-level list fields rather than treating the list as a single value
merge_dicts (True) – whether to recursively merge the contents of top-level dict fields rather than treating the dict as a single value
overwrite (True) – whether to overwrite (True) or skip (False) existing fields

modify(query=None, **update)#

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

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

Note

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

Parameters:

query – the update will be performed only if the document in the database matches the query
update – Django-style update keyword arguments

my_metaclass#: alias of TopLevelDocumentMetaclass

property pk#: Get the primary key.

classmethod register_delete_rule(document_cls, field_name, rule)#: This method registers the delete rules to apply when removing this object.

select_related(max_depth=1)#: Handles dereferencing of DBRef objects to a maximum depth in order to cut down the number queries to mongodb.

set_field(field_name, value, create=True)#

Sets the value of a field of the document.

Parameters:

field_name – the field name
value – the field value
create (True) – whether to create the field if it does not exist

Raises:

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

switch_collection(collection_name, keep_created=True)#

Temporarily switch the collection for a document instance.

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

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

Parameters:

collection_name (str) – The database alias to use for saving the document
keep_created (bool) – keep self._created value after switching collection, else is reset to True

See also

Use switch_db if you need to read from another database

switch_db(db_alias, keep_created=True)#

Temporarily switch the database for a document instance.

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

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

Parameters:

db_alias (str) – The database alias to use for saving the document
keep_created (bool) – keep self._created value after switching db, else is reset to True

See also

Use switch_collection if you need to read from another collection

to_dbref()#: Returns an instance of DBRef useful in __raw__ queries.

to_dict(extended=False)#

Serializes this document to a BSON/JSON dictionary.

Parameters:: extended (False) – whether to serialize extended JSON constructs such as ObjectIDs, Binary, etc. into JSON format
Returns:: a dict

to_json(pretty_print=False)#

Serializes the document to a JSON string.

Parameters:: pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations
Returns:: a JSON string

to_mongo(*args, **kwargs)#: Return as SON data ready for use with MongoDB.

update(**kwargs)#

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

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

validate(clean=True)#

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

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

class fiftyone.core.odm.SerializableDocument#

Bases: object

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

Attributes:

field_names

An ordered tuple of the public fields of this document.

Methods:

`fancy_repr`([class_name, select_fields, ...])	Generates a customizable string representation of the document.
`has_field`(field_name)	Determines whether the document has a field of the given name.
`get_field`(field_name)	Gets the field of the document.
`set_field`(field_name, value[, create])	Sets the value of a field of the document.
`clear_field`(field_name)	Clears the field from the document.
`iter_fields`()	Returns an iterator over the `(name, value)` pairs of the public fields of the document.
`copy`()	Returns a deep copy of the document.
`merge`(doc[, merge_lists, merge_dicts, overwrite])	Merges the contents of the given document into this document.
`to_dict`([extended])	Serializes this document to a BSON/JSON dictionary.
`from_dict`(d[, extended])	Loads the document from a BSON/JSON dictionary.
`to_json`([pretty_print])	Serializes the document to a JSON string.
`from_json`(s)	Loads the document from a JSON string.

property field_names#: An ordered tuple of the public fields of this document.

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

Generates a customizable string representation of the document.

Parameters:

class_name (None) – optional class name to use
select_fields (None) – iterable of field names to restrict to
exclude_fields (None) – iterable of field names to exclude
**kwargs – additional key-value pairs to include in the string representation

Returns:

a string representation of the document

has_field(field_name)#

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

Parameters:: field_name – the field name
Returns:: True/False

get_field(field_name)#

Gets the field of the document.

Parameters:: field_name – the field name
Returns:: the field value
Raises:: AttributeError – if the field does not exist

set_field(field_name, value, create=True)#

Sets the value of a field of the document.

Parameters:

field_name – the field name
value – the field value
create (True) – whether to create the field if it does not exist

Raises:

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

clear_field(field_name)#

Clears the field from the document.

Parameters:: field_name – the field name
Raises:: ValueError – if the field does not exist

iter_fields()#

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

Returns:: an iterator that emits (name, value) tuples

copy()#

Returns a deep copy of the document.

Returns:: a SerializableDocument

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

Merges the contents of the given document into this document.

Parameters:

doc – a SerializableDocument of same type as this document
merge_lists (True) – whether to merge the elements of top-level list fields rather than treating the list as a single value
merge_dicts (True) – whether to recursively merge the contents of top-level dict fields rather than treating the dict as a single value
overwrite (True) – whether to overwrite (True) or skip (False) existing fields

to_dict(extended=False)#

Serializes this document to a BSON/JSON dictionary.

Parameters:: extended (False) – whether to serialize extended JSON constructs such as ObjectIDs, Binary, etc. into JSON format
Returns:: a dict

classmethod from_dict(d, extended=False)#

Loads the document from a BSON/JSON dictionary.

Parameters:

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

Returns:

a SerializableDocument

to_json(pretty_print=False)#

Serializes the document to a JSON string.

Parameters:: pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations
Returns:: a JSON string

classmethod from_json(s)#

Loads the document from a JSON string.

Returns:: a SerializableDocument

class fiftyone.core.odm.BaseEmbeddedDocument#

Bases: MongoEngineBaseDocument

Base class for documents that are embedded within other documents and therefore are not stored in their own collection in the database.

Methods:

`clear_field`(field_name)	Clears the field from the document.
`copy`()	Returns a deep copy of the document.
`fancy_repr`([class_name, select_fields, ...])	Generates a customizable string representation of the document.
`field_to_mongo`(field_name)
`field_to_python`(field_name, value)
`from_dict`(d[, extended])	Loads the document from a BSON/JSON dictionary.
`from_json`(s)	Loads the document from a JSON string.
`get_field`(field_name)	Gets the field of the document.
`has_field`(field_name)	Determines whether the document has a field of the given name.
`iter_fields`()	Returns an iterator over the `(name, value)` pairs of the public fields of the document.
`merge`(doc[, merge_lists, merge_dicts, overwrite])	Merges the contents of the given document into this document.
`set_field`(field_name, value[, create])	Sets the value of a field of the document.
`to_dict`([extended])	Serializes this document to a BSON/JSON dictionary.
`to_json`([pretty_print])	Serializes the document to a JSON string.

Attributes:

field_names

An ordered tuple of the public fields of this document.

clear_field(field_name)#

Clears the field from the document.

Parameters:: field_name – the field name
Raises:: ValueError – if the field does not exist

copy()#

Returns a deep copy of the document.

Returns:: a SerializableDocument

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

Generates a customizable string representation of the document.

Parameters:

class_name (None) – optional class name to use
select_fields (None) – iterable of field names to restrict to
exclude_fields (None) – iterable of field names to exclude
**kwargs – additional key-value pairs to include in the string representation

Returns:

a string representation of the document

property field_names#: An ordered tuple of the public fields of this document.

field_to_mongo(field_name)#

field_to_python(field_name, value)#

classmethod from_dict(d, extended=False)#

Loads the document from a BSON/JSON dictionary.

Parameters:

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

Returns:

a SerializableDocument

classmethod from_json(s)#

Loads the document from a JSON string.

Returns:: a SerializableDocument

get_field(field_name)#

Gets the field of the document.

Parameters:: field_name – the field name
Returns:: the field value
Raises:: AttributeError – if the field does not exist

has_field(field_name)#

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

Parameters:: field_name – the field name
Returns:: True/False

iter_fields()#

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

Returns:: an iterator that emits (name, value) tuples

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

Merges the contents of the given document into this document.

Parameters:

doc – a SerializableDocument of same type as this document
merge_lists (True) – whether to merge the elements of top-level list fields rather than treating the list as a single value
merge_dicts (True) – whether to recursively merge the contents of top-level dict fields rather than treating the dict as a single value
overwrite (True) – whether to overwrite (True) or skip (False) existing fields

set_field(field_name, value, create=True)#

Sets the value of a field of the document.

Parameters:

field_name – the field name
value – the field value
create (True) – whether to create the field if it does not exist

Raises:

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

to_dict(extended=False)#

Serializes this document to a BSON/JSON dictionary.

Parameters:: extended (False) – whether to serialize extended JSON constructs such as ObjectIDs, Binary, etc. into JSON format
Returns:: a dict

to_json(pretty_print=False)#

Serializes the document to a JSON string.

Parameters:: pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations
Returns:: a JSON string

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

Bases: DynamicMixin, BaseEmbeddedDocument, DynamicEmbeddedDocument

Base class for dynamic documents that are embedded within other documents and therefore aren’t stored in their own collection in the database.

Dynamic documents can have arbitrary fields added to them.

Attributes:

`STRICT`
`field_names`	An ordered tuple of the public fields of this document.

Methods:

`clean`()	Hook for doing document level data cleaning (usually validation or assignment) before validation is run.
`clear_field`(field_name)	Clears the field from the document.
`copy`()	Returns a deep copy of the document.
`fancy_repr`([class_name, select_fields, ...])	Generates a customizable string representation of the document.
`field_to_mongo`(field_name)
`field_to_python`(field_name, value)
`from_dict`(d[, extended])	Loads the document from a BSON/JSON dictionary.
`from_json`(s)	Loads the document from a JSON string.
`get_field`(field_name)	Gets the field of the document.
`get_text_score`()	Get text score from text query
`has_field`(field_name)	Determines whether the document has a field of the given name.
`iter_fields`()	Returns an iterator over the `(name, value)` pairs of the public fields of the document.
`merge`(doc[, merge_lists, merge_dicts, overwrite])	Merges the contents of the given document into this document.
`set_field`(field_name, value[, create])	Sets the value of a field of the document.
`to_dict`([extended])	Serializes this document to a BSON/JSON dictionary.
`to_json`([pretty_print])	Serializes the document to a JSON string.
`to_mongo`(args, *kwargs)	Return as SON data ready for use with MongoDB.
`validate`([clean])	Ensure that all fields' values are valid and that required fields are present.

Classes:

my_metaclass

alias of DocumentMetaclass

STRICT = False#

clean()#

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

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

clear_field(field_name)#

Clears the field from the document.

Parameters:: field_name – the field name
Raises:: ValueError – if the field does not exist

copy()#

Returns a deep copy of the document.

Returns:: a SerializableDocument

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

Generates a customizable string representation of the document.

Parameters:

class_name (None) – optional class name to use
select_fields (None) – iterable of field names to restrict to
exclude_fields (None) – iterable of field names to exclude
**kwargs – additional key-value pairs to include in the string representation

Returns:

a string representation of the document

property field_names#: An ordered tuple of the public fields of this document.

field_to_mongo(field_name)#

field_to_python(field_name, value)#

classmethod from_dict(d, extended=False)#

Loads the document from a BSON/JSON dictionary.

Parameters:

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

Returns:

a SerializableDocument

classmethod from_json(s)#

Loads the document from a JSON string.

Returns:: a SerializableDocument

get_field(field_name)#

Gets the field of the document.

Parameters:: field_name – the field name
Returns:: the field value
Raises:: AttributeError – if the field does not exist

get_text_score()#: Get text score from text query

has_field(field_name)#

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

Parameters:: field_name – the field name
Returns:: True/False

iter_fields()#

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

Returns:: an iterator that emits (name, value) tuples

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

Merges the contents of the given document into this document.

Parameters:

doc – a SerializableDocument of same type as this document
merge_lists (True) – whether to merge the elements of top-level list fields rather than treating the list as a single value
merge_dicts (True) – whether to recursively merge the contents of top-level dict fields rather than treating the dict as a single value
overwrite (True) – whether to overwrite (True) or skip (False) existing fields

my_metaclass#: alias of DocumentMetaclass

set_field(field_name, value, create=True)#

Sets the value of a field of the document.

Parameters:

field_name – the field name
value – the field value
create (True) – whether to create the field if it does not exist

Raises:

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

to_dict(extended=False)#

Serializes this document to a BSON/JSON dictionary.

Parameters:: extended (False) – whether to serialize extended JSON constructs such as ObjectIDs, Binary, etc. into JSON format
Returns:: a dict

to_json(pretty_print=False)#

Serializes the document to a JSON string.

Parameters:: pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations
Returns:: a JSON string

to_mongo(*args, **kwargs)#: Return as SON data ready for use with MongoDB.

validate(clean=True)#

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

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

exception fiftyone.core.odm.DynamicEmbeddedDocumentException#

Bases: Exception

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

Methods:

`add_note`	Exception.add_note(note) -- add a note to the exception
`with_traceback`	Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

Attributes:

args

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

args#

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

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

Bases: BaseEmbeddedDocument, EmbeddedDocument

Base class for documents that are embedded within other documents and therefore are not stored in their own collection in the database.

Attributes:

`STRICT`
`field_names`	An ordered tuple of the public fields of this document.

Methods:

`clean`()	Hook for doing document level data cleaning (usually validation or assignment) before validation is run.
`clear_field`(field_name)	Clears the field from the document.
`copy`()	Returns a deep copy of the document.
`fancy_repr`([class_name, select_fields, ...])	Generates a customizable string representation of the document.
`field_to_mongo`(field_name)
`field_to_python`(field_name, value)
`from_dict`(d[, extended])	Loads the document from a BSON/JSON dictionary.
`from_json`(s)	Loads the document from a JSON string.
`get_field`(field_name)	Gets the field of the document.
`get_text_score`()	Get text score from text query
`has_field`(field_name)	Determines whether the document has a field of the given name.
`iter_fields`()	Returns an iterator over the `(name, value)` pairs of the public fields of the document.
`merge`(doc[, merge_lists, merge_dicts, overwrite])	Merges the contents of the given document into this document.
`set_field`(field_name, value[, create])	Sets the value of a field of the document.
`to_dict`([extended])	Serializes this document to a BSON/JSON dictionary.
`to_json`([pretty_print])	Serializes the document to a JSON string.
`to_mongo`(args, *kwargs)	Return as SON data ready for use with MongoDB.
`validate`([clean])	Ensure that all fields' values are valid and that required fields are present.

Classes:

my_metaclass

alias of DocumentMetaclass

STRICT = False#

clean()#

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

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

clear_field(field_name)#

Clears the field from the document.

Parameters:: field_name – the field name
Raises:: ValueError – if the field does not exist

copy()#

Returns a deep copy of the document.

Returns:: a SerializableDocument

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

Generates a customizable string representation of the document.

Parameters:

class_name (None) – optional class name to use
select_fields (None) – iterable of field names to restrict to
exclude_fields (None) – iterable of field names to exclude
**kwargs – additional key-value pairs to include in the string representation

Returns:

a string representation of the document

property field_names#: An ordered tuple of the public fields of this document.

field_to_mongo(field_name)#

field_to_python(field_name, value)#

classmethod from_dict(d, extended=False)#

Loads the document from a BSON/JSON dictionary.

Parameters:

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

Returns:

a SerializableDocument

classmethod from_json(s)#

Loads the document from a JSON string.

Returns:: a SerializableDocument

get_field(field_name)#

Gets the field of the document.

Parameters:: field_name – the field name
Returns:: the field value
Raises:: AttributeError – if the field does not exist

get_text_score()#: Get text score from text query

has_field(field_name)#

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

Parameters:: field_name – the field name
Returns:: True/False

iter_fields()#

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

Returns:: an iterator that emits (name, value) tuples

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

Merges the contents of the given document into this document.

Parameters:

doc – a SerializableDocument of same type as this document
merge_lists (True) – whether to merge the elements of top-level list fields rather than treating the list as a single value
merge_dicts (True) – whether to recursively merge the contents of top-level dict fields rather than treating the dict as a single value
overwrite (True) – whether to overwrite (True) or skip (False) existing fields

my_metaclass#: alias of DocumentMetaclass

set_field(field_name, value, create=True)#

Sets the value of a field of the document.

Parameters:

field_name – the field name
value – the field value
create (True) – whether to create the field if it does not exist

Raises:

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

to_dict(extended=False)#

Serializes this document to a BSON/JSON dictionary.

Parameters:: extended (False) – whether to serialize extended JSON constructs such as ObjectIDs, Binary, etc. into JSON format
Returns:: a dict

to_json(pretty_print=False)#

Serializes the document to a JSON string.

Parameters:: pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations
Returns:: a JSON string

to_mongo(*args, **kwargs)#: Return as SON data ready for use with MongoDB.

validate(clean=True)#

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

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

class fiftyone.core.odm.DatasetFrameDocument(**kwargs)#

Bases: DatasetMixin, Document

Attributes:

`id`	An Object ID field.
`frame_number`	A video frame number field.
`created_at`	A datetime field.
`last_modified_at`	A datetime field.
`STRICT`
`collection_name`
`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:

`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.
`clean`()	Hook for doing document level data cleaning (usually validation or assignment) before validation is run.
`clear_field`(field_name)	Clears the field from the document.
`compare_indexes`()	Compares the indexes defined in MongoEngine with the ones existing in the database.
`copy`([new_id])	Returns a deep copy of the document.
`copy_with_new_id`()
`create_index`(keys[, background])	Creates the given indexes if required.
`delete`([signal_kwargs])	Delete the `Document` from the database.
`drop_collection`()	Drops the entire collection associated with this `Document` type from the database.
`ensure_indexes`()	Checks the document meta data and ensures all the indexes exist.
`fancy_repr`([class_name, select_fields, ...])	Generates a customizable string representation of the document.
`field_to_mongo`(field_name)
`field_to_python`(field_name, value)
`from_dict`(d[, extended])	Loads the document from a BSON/JSON dictionary.
`from_json`(s)	Loads the document from a JSON string.
`get_field`(field_name)	Gets the field of the document.
`get_field_schema`([ftype, embedded_doc_type, ...])	Returns a schema dictionary describing the fields of this document.
`get_text_score`()	Get text score from text query
`has_field`(field_name)	Determines whether the document has a field of the given name.
`iter_fields`()	Returns an iterator over the `(name, value)` pairs of the public fields of the document.
`list_indexes`()	Lists all indexes that should be created for the Document collection.
`merge`(doc[, merge_lists, merge_dicts, overwrite])	Merges the contents of the given document into this document.
`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 the document from the database.
`save`([upsert, validate, 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.
`to_dbref`()	Returns an instance of `DBRef` useful in __raw__ queries.
`to_dict`([extended])	Serializes this document to a BSON/JSON dictionary.
`to_json`([pretty_print])	Serializes the document to a JSON string.
`to_mongo`(args, *kwargs)	Return as SON data ready for use with MongoDB.
`update`(**kwargs)	Performs an update on the `Document` A convenience wrapper to `update()`.
`validate`([clean])	Ensure that all fields' values are valid and that required fields are present.

Classes:

my_metaclass

alias of TopLevelDocumentMetaclass

id#

An Object ID field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

frame_number#

A video frame number field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

created_at#

A datetime field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

last_modified_at#

A datetime field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

STRICT = False#

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

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

Parameters:

path – the field name or embedded.field.name
ftype – the field type to create. Must be a subclass of fiftyone.core.fields.Field
embedded_doc_type (None) – the fiftyone.core.odm.BaseEmbeddedDocument type of the field. Only applicable when ftype is fiftyone.core.fields.EmbeddedDocumentField
subfield (None) – the fiftyone.core.fields.Field type of the contained field. Only applicable when ftype is fiftyone.core.fields.ListField or fiftyone.core.fields.DictField
fields (None) – a list of fiftyone.core.fields.Field instances defining embedded document attributes. Only applicable when ftype is fiftyone.core.fields.EmbeddedDocumentField
description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field should be read-only
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)
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

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

Clears the field from the document.

Parameters:: field_name – the field name
Raises:: ValueError – if the field does not exist

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(new_id=False)#

Returns a deep copy of the document.

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

copy_with_new_id()#

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

Creates the given indexes if required.

Parameters:

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

delete(signal_kwargs=None, **write_concern)#

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

Parameters:

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

classmethod drop_collection()#

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

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

classmethod ensure_indexes()#

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

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

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

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

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

Note

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

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

Generates a customizable string representation of the document.

Parameters:

class_name (None) – optional class name to use
select_fields (None) – iterable of field names to restrict to
exclude_fields (None) – iterable of field names to exclude
**kwargs – additional key-value pairs to include in the string representation

Returns:

a string representation of the document

property field_names#: An ordered tuple of the public fields of this document.

field_to_mongo(field_name)#

field_to_python(field_name, value)#

classmethod from_dict(d, extended=False)#

Loads the document from a BSON/JSON dictionary.

Parameters:

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

Returns:

a SerializableDocument

classmethod from_json(s)#

Loads the document from a JSON string.

Returns:: a SerializableDocument

get_field(field_name)#

Gets the field of the document.

Parameters:: field_name – the field name
Returns:: the field value
Raises:: AttributeError – if the field does not exist

classmethod get_field_schema(ftype=None, embedded_doc_type=None, subfield=None, read_only=None, info_keys=None, created_after=None, include_private=False, flat=False, unwind=True, mode=None)#

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
subfield (None) – an optional subfield type or iterable of subfield types to which to restrict the returned schema. Must be subclass(es) of fiftyone.core.fields.Field
read_only (None) – whether to restrict to (True) or exclude (False) read-only fields. By default, all fields are included
info_keys (None) – an optional key or list of keys that must be in the field’s info dict
created_after (None) – an optional datetime specifying a minimum creation date
include_private (False) – whether to include fields that start with _ in the returned schema
flat (False) – whether to return a flattened schema where all embedded document fields are included as top-level keys
unwind (True) – whether to traverse into list fields. Only applicable when flat=True
mode (None) – whether to apply the above constraints before and/or after flattening the schema. Only applicable when flat=True. Supported values are ("before", "after", "both"). The default is "after"

Returns:

a dict mapping field names to fiftyone.core.fields.Field instances

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

classmethod merge_field_schema(schema, expand_schema=True, recursive=True, validate=True, overwrite=False)#

Merges the field schema into this document.

Parameters:

schema – a dict mapping field names or embedded.field.names to 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 fields against existing fields at the same path
overwrite (False) – whether to overwrite the editable metadata of existing fields

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 TopLevelDocumentMetaclass

property pk#: Get the primary key.

classmethod register_delete_rule(document_cls, field_name, rule)#: This method registers the delete rules to apply when removing this object.

reload(*fields, **kwargs)#

Reloads the document from the database.

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

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

Saves the document to the database.

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

Parameters:

upsert (False) – whether to insert the document if it has an id populated but no document with that ID exists in the database
validate (True) – whether to validate the document
safe (False) – whether to reload() the document before raising any errors

Returns:

self

select_related(max_depth=1)#: 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, _enforce_read_only=True)#

Sets the value of a field of the document.

Parameters:

field_name – the field name
value – the field value
create (True) – whether to create the field if it does not exist

Raises:

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

switch_collection(collection_name, keep_created=True)#

Temporarily switch the collection for a document instance.

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

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

Parameters:

collection_name (str) – The database alias to use for saving the document
keep_created (bool) – keep self._created value after switching collection, else is reset to True

See also

Use switch_db if you need to read from another database

switch_db(db_alias, keep_created=True)#

Temporarily switch the database for a document instance.

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

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

Parameters:

db_alias (str) – The database alias to use for saving the document
keep_created (bool) – keep self._created value after switching db, else is reset to True

See also

Use switch_collection if you need to read from another collection

to_dbref()#: Returns an instance of DBRef useful in __raw__ queries.

to_dict(extended=False)#

Serializes this document to a BSON/JSON dictionary.

Parameters:: extended (False) – whether to serialize extended JSON constructs such as ObjectIDs, Binary, etc. into JSON format
Returns:: a dict

to_json(pretty_print=False)#

Serializes the document to a JSON string.

Parameters:: pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations
Returns:: a JSON string

to_mongo(*args, **kwargs)#: Return as SON data ready for use with MongoDB.

update(**kwargs)#

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

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

validate(clean=True)#

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

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

class fiftyone.core.odm.NoDatasetFrameDocument(**kwargs)#

Bases: NoDatasetMixin, SerializableDocument

Attributes:

`default_fields`
`default_fields_ordered`
`field_names`	An ordered tuple of the public fields of this document.
`in_db`

Methods:

`clear_field`(field_name)	Clears the field from the document.
`copy`()	Returns a deep copy of the document.
`delete`()
`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.
`from_json`(s)	Loads the document from a JSON string.
`get_field`(field_name)	Gets the field of the document.
`has_field`(field_name)	Determines whether the document has a field of the given name.
`iter_fields`()	Returns an iterator over the `(name, value)` pairs of the public fields of the document.
`merge`(doc[, merge_lists, merge_dicts, overwrite])	Merges the contents of the given document into this document.
`reload`()
`save`()
`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.

default_fields = {'_dataset_id': <fiftyone.core.fields.ObjectIdField object>, '_sample_id': <fiftyone.core.fields.ObjectIdField object>, 'created_at': <fiftyone.core.fields.DateTimeField object>, 'frame_number': <fiftyone.core.fields.FrameNumberField object>, 'id': <fiftyone.core.fields.ObjectIdField object>, 'last_modified_at': <fiftyone.core.fields.DateTimeField object>}#

default_fields_ordered = ('id', 'frame_number', 'created_at', 'last_modified_at', '_sample_id', '_dataset_id')#

clear_field(field_name)#

Clears the field from the document.

Parameters:: field_name – the field name
Raises:: ValueError – if the field does not exist

copy()#

Returns a deep copy of the document.

Returns:: a SerializableDocument

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#: An ordered tuple of the public fields of this document.

classmethod from_dict(d, extended=False)#

Loads the document from a BSON/JSON dictionary.

Parameters:

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

Returns:

a SerializableDocument

classmethod from_json(s)#

Loads the document from a JSON string.

Returns:: a SerializableDocument

get_field(field_name)#

Gets the field of the document.

Parameters:: field_name – the field name
Returns:: the field value
Raises:: AttributeError – if the field does not exist

has_field(field_name)#

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

Parameters:: field_name – the field name
Returns:: True/False

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

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

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

Bases: Document

Backing document for dataset runs.

Attributes:

`dataset_id`	An Object ID field.
`key`	A unicode string field.
`version`	A unicode string field.
`timestamp`	A datetime field.
`config`	A dictionary field that wraps a standard Python dictionary.
`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.
`results`	A GridFS storage field.
`STRICT`
`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.
`pk`	Get the primary key.

Miscellaneous:

`DoesNotExist`
`MultipleObjectsReturned`

Methods:

`cascade_save`(**kwargs)	Recursively save any references and generic references on the document.
`clean`()	Hook for doing document level data cleaning (usually validation or assignment) before validation is run.
`clear_field`(field_name)	Clears the field from the document.
`compare_indexes`()	Compares the indexes defined in MongoEngine with the ones existing in the database.
`copy`([new_id])	Returns a deep copy of the document.
`copy_with_new_id`()
`create_index`(keys[, background])	Creates the given indexes if required.
`delete`([signal_kwargs])	Delete the `Document` from the database.
`drop_collection`()	Drops the entire collection associated with this `Document` type from the database.
`ensure_indexes`()	Checks the document meta data and ensures all the indexes exist.
`fancy_repr`([class_name, select_fields, ...])	Generates a customizable string representation of the document.
`field_to_mongo`(field_name)
`field_to_python`(field_name, value)
`from_dict`(d[, extended])	Loads the document from a BSON/JSON dictionary.
`from_json`(s)	Loads the document from a JSON string.
`get_field`(field_name)	Gets the field of the document.
`get_text_score`()	Get text score from text query
`has_field`(field_name)	Determines whether the document has a field of the given name.
`iter_fields`()	Returns an iterator over the `(name, value)` pairs of the public fields of the document.
`list_indexes`()	Lists all indexes that should be created for the Document collection.
`merge`(doc[, merge_lists, merge_dicts, overwrite])	Merges the contents of the given document into this document.
`modify`([query])	Perform an atomic update of the document in the database and reload the document object using updated version.
`register_delete_rule`(document_cls, ...)	This method registers the delete rules to apply when removing this object.
`reload`(fields, *kwargs)	Reloads the document from the database.
`save`([upsert, validate, 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.
`to_dbref`()	Returns an instance of `DBRef` useful in __raw__ queries.
`to_dict`([extended])	Serializes this document to a BSON/JSON dictionary.
`to_json`([pretty_print])	Serializes the document to a JSON string.
`to_mongo`(args, *kwargs)	Return as SON data ready for use with MongoDB.
`update`(**kwargs)	Performs an update on the `Document` A convenience wrapper to `update()`.
`validate`([clean])	Ensure that all fields' values are valid and that required fields are present.

Classes:

my_metaclass

alias of TopLevelDocumentMetaclass

dataset_id#

An Object ID field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

key#

A unicode string field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

version#

A unicode string field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

timestamp#

A datetime field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

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
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

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
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

results#: A GridFS storage field.

exception DoesNotExist#

Bases: DoesNotExist

Methods:

`add_note`	Exception.add_note(note) -- add a note to the exception
`with_traceback`	Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

Attributes:

args

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

args#

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

exception MultipleObjectsReturned#

Bases: MultipleObjectsReturned

Methods:

`add_note`	Exception.add_note(note) -- add a note to the exception
`with_traceback`	Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

Attributes:

args

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

args#

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

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(new_id=False)#

Returns a deep copy of the document.

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

copy_with_new_id()#

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

Creates the given indexes if required.

Parameters:

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

delete(signal_kwargs=None, **write_concern)#

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

Parameters:

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

classmethod drop_collection()#

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

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

classmethod ensure_indexes()#

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

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

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

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

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

Note

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

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

Generates a customizable string representation of the document.

Parameters:

class_name (None) – optional class name to use
select_fields (None) – iterable of field names to restrict to
exclude_fields (None) – iterable of field names to exclude
**kwargs – additional key-value pairs to include in the string representation

Returns:

a string representation of the document

property field_names#: An ordered tuple of the public fields of this document.

field_to_mongo(field_name)#

field_to_python(field_name, value)#

classmethod from_dict(d, extended=False)#

Loads the document from a BSON/JSON dictionary.

Parameters:

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

Returns:

a SerializableDocument

classmethod from_json(s)#

Loads the document from a JSON string.

Returns:: a SerializableDocument

get_field(field_name)#

Gets the field of the document.

Parameters:: field_name – the field name
Returns:: the field value
Raises:: AttributeError – if the field does not exist

get_text_score()#: Get text score from text query

has_field(field_name)#

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

Parameters:: field_name – the field name
Returns:: True/False

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 TopLevelDocumentMetaclass

property pk#: Get the primary key.

classmethod register_delete_rule(document_cls, field_name, rule)#: This method registers the delete rules to apply when removing this object.

reload(*fields, **kwargs)#

Reloads the document from the database.

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

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

Saves the document to the database.

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

Parameters:

upsert (False) – whether to insert the document if it has an id populated but no document with that ID exists in the database
validate (True) – whether to validate the document
safe (False) – whether to reload() the document before raising any errors

Returns:

self

select_related(max_depth=1)#: Handles dereferencing of DBRef objects to a maximum depth in order to cut down the number queries to mongodb.

set_field(field_name, value, create=True)#

Sets the value of a field of the document.

Parameters:

field_name – the field name
value – the field value
create (True) – whether to create the field if it does not exist

Raises:

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

switch_collection(collection_name, keep_created=True)#

Temporarily switch the collection for a document instance.

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

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

Parameters:

collection_name (str) – The database alias to use for saving the document
keep_created (bool) – keep self._created value after switching collection, else is reset to True

See also

Use switch_db if you need to read from another database

switch_db(db_alias, keep_created=True)#

Temporarily switch the database for a document instance.

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

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

Parameters:

db_alias (str) – The database alias to use for saving the document
keep_created (bool) – keep self._created value after switching db, else is reset to True

See also

Use switch_collection if you need to read from another collection

to_dbref()#: Returns an instance of DBRef useful in __raw__ queries.

to_dict(extended=False)#

Serializes this document to a BSON/JSON dictionary.

Parameters:: extended (False) – whether to serialize extended JSON constructs such as ObjectIDs, Binary, etc. into JSON format
Returns:: a dict

to_json(pretty_print=False)#

Serializes the document to a JSON string.

Parameters:: pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations
Returns:: a JSON string

to_mongo(*args, **kwargs)#: Return as SON data ready for use with MongoDB.

update(**kwargs)#

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

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

validate(clean=True)#

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

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

class fiftyone.core.odm.DatasetSampleDocument(**kwargs)#

Bases: DatasetMixin, Document

Base class for sample documents backing samples in datasets.

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

Attributes:

`id`	An Object ID field.
`filepath`	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.
`metadata`	A field that stores instances of a given type of `fiftyone.core.odm.BaseEmbeddedDocument` object.
`created_at`	A datetime field.
`last_modified_at`	A datetime field.
`media_type`
`STRICT`
`collection_name`
`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:

`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.
`clean`()	Hook for doing document level data cleaning (usually validation or assignment) before validation is run.
`clear_field`(field_name)	Clears the field from the document.
`compare_indexes`()	Compares the indexes defined in MongoEngine with the ones existing in the database.
`copy`([new_id])	Returns a deep copy of the document.
`copy_with_new_id`()
`create_index`(keys[, background])	Creates the given indexes if required.
`delete`([signal_kwargs])	Delete the `Document` from the database.
`drop_collection`()	Drops the entire collection associated with this `Document` type from the database.
`ensure_indexes`()	Checks the document meta data and ensures all the indexes exist.
`fancy_repr`([class_name, select_fields, ...])	Generates a customizable string representation of the document.
`field_to_mongo`(field_name)
`field_to_python`(field_name, value)
`from_dict`(d[, extended])	Loads the document from a BSON/JSON dictionary.
`from_json`(s)	Loads the document from a JSON string.
`get_field`(field_name)	Gets the field of the document.
`get_field_schema`([ftype, embedded_doc_type, ...])	Returns a schema dictionary describing the fields of this document.
`get_text_score`()	Get text score from text query
`has_field`(field_name)	Determines whether the document has a field of the given name.
`iter_fields`()	Returns an iterator over the `(name, value)` pairs of the public fields of the document.
`list_indexes`()	Lists all indexes that should be created for the Document collection.
`merge`(doc[, merge_lists, merge_dicts, overwrite])	Merges the contents of the given document into this document.
`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 the document from the database.
`save`([upsert, validate, 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.
`to_dbref`()	Returns an instance of `DBRef` useful in __raw__ queries.
`to_dict`([extended])	Serializes this document to a BSON/JSON dictionary.
`to_json`([pretty_print])	Serializes the document to a JSON string.
`to_mongo`(args, *kwargs)	Return as SON data ready for use with MongoDB.
`update`(**kwargs)	Performs an update on the `Document` A convenience wrapper to `update()`.
`validate`([clean])	Ensure that all fields' values are valid and that required fields are present.

Classes:

my_metaclass

alias of TopLevelDocumentMetaclass

id#

An Object ID field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

filepath#

A unicode string field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

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
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

metadata#

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

Parameters:

document_type – the fiftyone.core.odm.BaseEmbeddedDocument type stored in this field
description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

created_at#

A datetime field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

last_modified_at#

A datetime field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

property media_type#

STRICT = False#

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

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

Parameters:

path – the field name or embedded.field.name
ftype – the field type to create. Must be a subclass of fiftyone.core.fields.Field
embedded_doc_type (None) – the fiftyone.core.odm.BaseEmbeddedDocument type of the field. Only applicable when ftype is fiftyone.core.fields.EmbeddedDocumentField
subfield (None) – the fiftyone.core.fields.Field type of the contained field. Only applicable when ftype is fiftyone.core.fields.ListField or fiftyone.core.fields.DictField
fields (None) – a list of fiftyone.core.fields.Field instances defining embedded document attributes. Only applicable when ftype is fiftyone.core.fields.EmbeddedDocumentField
description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field should be read-only
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)
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

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

Clears the field from the document.

Parameters:: field_name – the field name
Raises:: ValueError – if the field does not exist

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(new_id=False)#

Returns a deep copy of the document.

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

copy_with_new_id()#

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

Creates the given indexes if required.

Parameters:

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

delete(signal_kwargs=None, **write_concern)#

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

Parameters:

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

classmethod drop_collection()#

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

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

classmethod ensure_indexes()#

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

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

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

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

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

Note

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

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

Generates a customizable string representation of the document.

Parameters:

class_name (None) – optional class name to use
select_fields (None) – iterable of field names to restrict to
exclude_fields (None) – iterable of field names to exclude
**kwargs – additional key-value pairs to include in the string representation

Returns:

a string representation of the document

property field_names#: An ordered tuple of the public fields of this document.

field_to_mongo(field_name)#

field_to_python(field_name, value)#

classmethod from_dict(d, extended=False)#

Loads the document from a BSON/JSON dictionary.

Parameters:

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

Returns:

a SerializableDocument

classmethod from_json(s)#

Loads the document from a JSON string.

Returns:: a SerializableDocument

get_field(field_name)#

Gets the field of the document.

Parameters:: field_name – the field name
Returns:: the field value
Raises:: AttributeError – if the field does not exist

classmethod get_field_schema(ftype=None, embedded_doc_type=None, subfield=None, read_only=None, info_keys=None, created_after=None, include_private=False, flat=False, unwind=True, mode=None)#

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
subfield (None) – an optional subfield type or iterable of subfield types to which to restrict the returned schema. Must be subclass(es) of fiftyone.core.fields.Field
read_only (None) – whether to restrict to (True) or exclude (False) read-only fields. By default, all fields are included
info_keys (None) – an optional key or list of keys that must be in the field’s info dict
created_after (None) – an optional datetime specifying a minimum creation date
include_private (False) – whether to include fields that start with _ in the returned schema
flat (False) – whether to return a flattened schema where all embedded document fields are included as top-level keys
unwind (True) – whether to traverse into list fields. Only applicable when flat=True
mode (None) – whether to apply the above constraints before and/or after flattening the schema. Only applicable when flat=True. Supported values are ("before", "after", "both"). The default is "after"

Returns:

a dict mapping field names to fiftyone.core.fields.Field instances

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

classmethod merge_field_schema(schema, expand_schema=True, recursive=True, validate=True, overwrite=False)#

Merges the field schema into this document.

Parameters:

schema – a dict mapping field names or embedded.field.names to 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 fields against existing fields at the same path
overwrite (False) – whether to overwrite the editable metadata of existing fields

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 TopLevelDocumentMetaclass

property pk#: Get the primary key.

classmethod register_delete_rule(document_cls, field_name, rule)#: This method registers the delete rules to apply when removing this object.

reload(*fields, **kwargs)#

Reloads the document from the database.

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

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

Saves the document to the database.

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

Parameters:

upsert (False) – whether to insert the document if it has an id populated but no document with that ID exists in the database
validate (True) – whether to validate the document
safe (False) – whether to reload() the document before raising any errors

Returns:

self

select_related(max_depth=1)#: 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, _enforce_read_only=True)#

Sets the value of a field of the document.

Parameters:

field_name – the field name
value – the field value
create (True) – whether to create the field if it does not exist

Raises:

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

switch_collection(collection_name, keep_created=True)#

Temporarily switch the collection for a document instance.

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

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

Parameters:

collection_name (str) – The database alias to use for saving the document
keep_created (bool) – keep self._created value after switching collection, else is reset to True

See also

Use switch_db if you need to read from another database

switch_db(db_alias, keep_created=True)#

Temporarily switch the database for a document instance.

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

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

Parameters:

db_alias (str) – The database alias to use for saving the document
keep_created (bool) – keep self._created value after switching db, else is reset to True

See also

Use switch_collection if you need to read from another collection

to_dbref()#: Returns an instance of DBRef useful in __raw__ queries.

to_dict(extended=False)#

Serializes this document to a BSON/JSON dictionary.

Parameters:: extended (False) – whether to serialize extended JSON constructs such as ObjectIDs, Binary, etc. into JSON format
Returns:: a dict

to_json(pretty_print=False)#

Serializes the document to a JSON string.

Parameters:: pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations
Returns:: a JSON string

to_mongo(*args, **kwargs)#: Return as SON data ready for use with MongoDB.

update(**kwargs)#

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

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

validate(clean=True)#

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

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

class fiftyone.core.odm.NoDatasetSampleDocument(**kwargs)#

Bases: NoDatasetMixin, SerializableDocument

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

Attributes:

`default_fields`
`default_fields_ordered`
`media_type`
`field_names`	An ordered tuple of the public fields of this document.
`in_db`

Methods:

`clear_field`(field_name)	Clears the field from the document.
`copy`()	Returns a deep copy of the document.
`delete`()
`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.
`from_json`(s)	Loads the document from a JSON string.
`get_field`(field_name)	Gets the field of the document.
`has_field`(field_name)	Determines whether the document has a field of the given name.
`iter_fields`()	Returns an iterator over the `(name, value)` pairs of the public fields of the document.
`merge`(doc[, merge_lists, merge_dicts, overwrite])	Merges the contents of the given document into this document.
`reload`()
`save`()
`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.

default_fields = {'_dataset_id': <fiftyone.core.fields.ObjectIdField object>, '_media_type': <fiftyone.core.fields.StringField object>, '_rand': <fiftyone.core.fields.FloatField object>, 'created_at': <fiftyone.core.fields.DateTimeField object>, 'filepath': <fiftyone.core.fields.StringField object>, 'id': <fiftyone.core.fields.ObjectIdField object>, 'last_modified_at': <fiftyone.core.fields.DateTimeField object>, 'metadata': <fiftyone.core.fields.EmbeddedDocumentField object>, 'tags': <fiftyone.core.fields.ListField object>}#

default_fields_ordered = ('id', 'filepath', 'tags', 'metadata', 'created_at', 'last_modified_at', '_media_type', '_rand', '_dataset_id')#

property media_type#

clear_field(field_name)#

Clears the field from the document.

Parameters:: field_name – the field name
Raises:: ValueError – if the field does not exist

copy()#

Returns a deep copy of the document.

Returns:: a SerializableDocument

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#: An ordered tuple of the public fields of this document.

classmethod from_dict(d, extended=False)#

Loads the document from a BSON/JSON dictionary.

Parameters:

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

Returns:

a SerializableDocument

classmethod from_json(s)#

Loads the document from a JSON string.

Returns:: a SerializableDocument

get_field(field_name)#

Gets the field of the document.

Parameters:: field_name – the field name
Returns:: the field value
Raises:: AttributeError – if the field does not exist

has_field(field_name)#

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

Parameters:: field_name – the field name
Returns:: True/False

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

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

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, read_only=False, created_at=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:

name – the field name
ftype – the field type to create. Must be a subclass of fiftyone.core.fields.Field
embedded_doc_type (None) – the fiftyone.core.odm.BaseEmbeddedDocument type of the field. Only applicable when ftype is fiftyone.core.fields.EmbeddedDocumentField
subfield (None) – the fiftyone.core.fields.Field type of the contained field. Only applicable when ftype is fiftyone.core.fields.ListField or fiftyone.core.fields.DictField
fields (None) – a list of fiftyone.core.fields.Field instances defining embedded document attributes. Only applicable when ftype is fiftyone.core.fields.EmbeddedDocumentField
db_field (None) – the database field to store this field in. By default, name is used
description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field should be read-only
created_at (None) – the datetime the field was created

Returns:

a fiftyone.core.fields.Field

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:

a fiftyone.core.fields.Field

fiftyone.core.odm.get_field_kwargs(field)#

Constructs the field keyword arguments dictionary for the given field.

Parameters:: field – a fiftyone.core.fields.Field or str(field) representation of one
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:

name – the field name or embedded.field.name
field – a fiftyone.core.fields.Field
existing_field – the reference fiftyone.core.fields.Field

Raises:

ValueError – if the fields do not match

class fiftyone.core.odm.SavedViewDocument(**kwargs)#

Bases: Document

Backing document for saved views.

Attributes:

`dataset_id`	An Object ID field.
`name`	A unicode string field.
`description`	A unicode string field.
`slug`	A unicode string field.
`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.
`created_at`	A datetime field.
`last_modified_at`	A datetime field.
`last_loaded_at`	A datetime field.
`STRICT`
`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.
`pk`	Get the primary key.

Miscellaneous:

`DoesNotExist`
`MultipleObjectsReturned`

Methods:

`cascade_save`(**kwargs)	Recursively save any references and generic references on the document.
`clean`()	Hook for doing document level data cleaning (usually validation or assignment) before validation is run.
`clear_field`(field_name)	Clears the field from the document.
`compare_indexes`()	Compares the indexes defined in MongoEngine with the ones existing in the database.
`copy`([new_id])	Returns a deep copy of the document.
`copy_with_new_id`()
`create_index`(keys[, background])	Creates the given indexes if required.
`delete`([signal_kwargs])	Delete the `Document` from the database.
`drop_collection`()	Drops the entire collection associated with this `Document` type from the database.
`ensure_indexes`()	Checks the document meta data and ensures all the indexes exist.
`fancy_repr`([class_name, select_fields, ...])	Generates a customizable string representation of the document.
`field_to_mongo`(field_name)
`field_to_python`(field_name, value)
`from_dict`(d[, extended])	Loads the document from a BSON/JSON dictionary.
`from_json`(s)	Loads the document from a JSON string.
`get_field`(field_name)	Gets the field of the document.
`get_text_score`()	Get text score from text query
`has_field`(field_name)	Determines whether the document has a field of the given name.
`iter_fields`()	Returns an iterator over the `(name, value)` pairs of the public fields of the document.
`list_indexes`()	Lists all indexes that should be created for the Document collection.
`merge`(doc[, merge_lists, merge_dicts, overwrite])	Merges the contents of the given document into this document.
`modify`([query])	Perform an atomic update of the document in the database and reload the document object using updated version.
`register_delete_rule`(document_cls, ...)	This method registers the delete rules to apply when removing this object.
`reload`(fields, *kwargs)	Reloads the document from the database.
`save`([upsert, validate, 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.
`to_dbref`()	Returns an instance of `DBRef` useful in __raw__ queries.
`to_dict`([extended])	Serializes this document to a BSON/JSON dictionary.
`to_json`([pretty_print])	Serializes the document to a JSON string.
`to_mongo`(args, *kwargs)	Return as SON data ready for use with MongoDB.
`update`(**kwargs)	Performs an update on the `Document` A convenience wrapper to `update()`.
`validate`([clean])	Ensure that all fields' values are valid and that required fields are present.

Classes:

my_metaclass

alias of TopLevelDocumentMetaclass

dataset_id#

An Object ID field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

name#

A unicode string field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

description#

A unicode string field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

slug#

A unicode string field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

color#

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

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

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
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

created_at#

A datetime field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

last_modified_at#

A datetime field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

last_loaded_at#

A datetime field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

exception DoesNotExist#

Bases: DoesNotExist

Methods:

`add_note`	Exception.add_note(note) -- add a note to the exception
`with_traceback`	Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

Attributes:

args

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

args#

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

exception MultipleObjectsReturned#

Bases: MultipleObjectsReturned

Methods:

`add_note`	Exception.add_note(note) -- add a note to the exception
`with_traceback`	Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

Attributes:

args

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

args#

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

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(new_id=False)#

Returns a deep copy of the document.

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

copy_with_new_id()#

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

Creates the given indexes if required.

Parameters:

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

delete(signal_kwargs=None, **write_concern)#

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

Parameters:

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

classmethod drop_collection()#

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

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

classmethod ensure_indexes()#

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

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

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

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

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

Note

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

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

Generates a customizable string representation of the document.

Parameters:

class_name (None) – optional class name to use
select_fields (None) – iterable of field names to restrict to
exclude_fields (None) – iterable of field names to exclude
**kwargs – additional key-value pairs to include in the string representation

Returns:

a string representation of the document

property field_names#: An ordered tuple of the public fields of this document.

field_to_mongo(field_name)#

field_to_python(field_name, value)#

classmethod from_dict(d, extended=False)#

Loads the document from a BSON/JSON dictionary.

Parameters:

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

Returns:

a SerializableDocument

classmethod from_json(s)#

Loads the document from a JSON string.

Returns:: a SerializableDocument

get_field(field_name)#

Gets the field of the document.

Parameters:: field_name – the field name
Returns:: the field value
Raises:: AttributeError – if the field does not exist

get_text_score()#: Get text score from text query

has_field(field_name)#

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

Parameters:: field_name – the field name
Returns:: True/False

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 TopLevelDocumentMetaclass

property pk#: Get the primary key.

classmethod register_delete_rule(document_cls, field_name, rule)#: This method registers the delete rules to apply when removing this object.

reload(*fields, **kwargs)#

Reloads the document from the database.

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

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

Saves the document to the database.

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

Parameters:

upsert (False) – whether to insert the document if it has an id populated but no document with that ID exists in the database
validate (True) – whether to validate the document
safe (False) – whether to reload() the document before raising any errors

Returns:

self

select_related(max_depth=1)#: Handles dereferencing of DBRef objects to a maximum depth in order to cut down the number queries to mongodb.

set_field(field_name, value, create=True)#

Sets the value of a field of the document.

Parameters:

field_name – the field name
value – the field value
create (True) – whether to create the field if it does not exist

Raises:

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

switch_collection(collection_name, keep_created=True)#

Temporarily switch the collection for a document instance.

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

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

Parameters:

collection_name (str) – The database alias to use for saving the document
keep_created (bool) – keep self._created value after switching collection, else is reset to True

See also

Use switch_db if you need to read from another database

switch_db(db_alias, keep_created=True)#

Temporarily switch the database for a document instance.

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

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

Parameters:

db_alias (str) – The database alias to use for saving the document
keep_created (bool) – keep self._created value after switching db, else is reset to True

See also

Use switch_collection if you need to read from another collection

to_dbref()#: Returns an instance of DBRef useful in __raw__ queries.

to_dict(extended=False)#

Serializes this document to a BSON/JSON dictionary.

Parameters:: extended (False) – whether to serialize extended JSON constructs such as ObjectIDs, Binary, etc. into JSON format
Returns:: a dict

to_json(pretty_print=False)#

Serializes the document to a JSON string.

Parameters:: pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations
Returns:: a JSON string

to_mongo(*args, **kwargs)#: Return as SON data ready for use with MongoDB.

update(**kwargs)#

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

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

validate(clean=True)#

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

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

fiftyone.core.odm.default_workspace_factory()#

Creates a default top-level instance of Space

Returns:: a default Space instance

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

Bases: AppComponent

Document for a panel (tab) within a Workspace in the App.

Parameters:

component_id – the component ID
type – the Panel type
pinned – whether the Panel is currently pinned
state – an optional Panel state dict

Attributes:

`type`	A unicode string field.
`pinned`	A boolean field.
`state`	A dictionary field that wraps a standard Python dictionary.
`STRICT`
`component_id`	A unicode string field.
`field_names`	An ordered tuple of the public fields of this document.

Methods:

`clean`()	Hook for doing document level data cleaning (usually validation or assignment) before validation is run.
`clear_field`(field_name)	Clears the field from the document.
`copy`()	Returns a deep copy of the document.
`fancy_repr`([class_name, select_fields, ...])	Generates a customizable string representation of the document.
`field_to_mongo`(field_name)
`field_to_python`(field_name, value)
`from_dict`(d[, extended])	Loads the document from a BSON/JSON dictionary.
`from_json`(s)	Loads the document from a JSON string.
`get_field`(field_name)	Gets the field of the document.
`get_text_score`()	Get text score from text query
`has_field`(field_name)	Determines whether the document has a field of the given name.
`iter_fields`()	Returns an iterator over the `(name, value)` pairs of the public fields of the document.
`merge`(doc[, merge_lists, merge_dicts, overwrite])	Merges the contents of the given document into this document.
`set_field`(field_name, value[, create])	Sets the value of a field of the document.
`to_dict`([extended])	Serializes this document to a BSON/JSON dictionary.
`to_json`([pretty_print])	Serializes the document to a JSON string.
`to_mongo`(args, *kwargs)	Return as SON data ready for use with MongoDB.
`validate`([clean])	Ensure that all fields' values are valid and that required fields are present.

Classes:

my_metaclass

alias of DocumentMetaclass

type#

A unicode string field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

pinned#

A boolean field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

state#

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
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

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

component_id#

A unicode string field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

copy()#

Returns a deep copy of the document.

Returns:: a SerializableDocument

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

Generates a customizable string representation of the document.

Parameters:

class_name (None) – optional class name to use
select_fields (None) – iterable of field names to restrict to
exclude_fields (None) – iterable of field names to exclude
**kwargs – additional key-value pairs to include in the string representation

Returns:

a string representation of the document

property field_names#: An ordered tuple of the public fields of this document.

field_to_mongo(field_name)#

field_to_python(field_name, value)#

classmethod from_dict(d, extended=False)#

Loads the document from a BSON/JSON dictionary.

Parameters:

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

Returns:

a SerializableDocument

classmethod from_json(s)#

Loads the document from a JSON string.

Returns:: a SerializableDocument

get_field(field_name)#

Gets the field of the document.

Parameters:: field_name – the field name
Returns:: the field value
Raises:: AttributeError – if the field does not exist

get_text_score()#: Get text score from text query

has_field(field_name)#

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

Parameters:: field_name – the field name
Returns:: True/False

iter_fields()#

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

Returns:: an iterator that emits (name, value) tuples

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

Merges the contents of the given document into this document.

Parameters:

doc – a SerializableDocument of same type as this document
merge_lists (True) – whether to merge the elements of top-level list fields rather than treating the list as a single value
merge_dicts (True) – whether to recursively merge the contents of top-level dict fields rather than treating the dict as a single value
overwrite (True) – whether to overwrite (True) or skip (False) existing fields

my_metaclass#: alias of DocumentMetaclass

set_field(field_name, value, create=True)#

Sets the value of a field of the document.

Parameters:

field_name – the field name
value – the field value
create (True) – whether to create the field if it does not exist

Raises:

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

to_dict(extended=False)#

Serializes this document to a BSON/JSON dictionary.

Parameters:: extended (False) – whether to serialize extended JSON constructs such as ObjectIDs, Binary, etc. into JSON format
Returns:: a dict

to_json(pretty_print=False)#

Serializes the document to a JSON string.

Parameters:: pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations
Returns:: a JSON string

to_mongo(*args, **kwargs)#: Return as SON data ready for use with MongoDB.

validate(clean=True)#

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

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

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

Bases: AppComponent

Document for configuration of a Space in the App.

Parameters:

component_id – the component’s ID
children – the list of Component children of this space, if any
orientation (["horizontal", "vertical"]) – the orientation of this space’s children
active_child – the component_id of this space’s currently active child
sizes – the ordered list of relative sizes for children of a space in [0, 1]

Attributes:

`children`	A list field that wraps a standard `Field`, allowing multiple instances of the field to be stored as a list in the database.
`orientation`	A unicode string field.
`active_child`	A unicode string field.
`sizes`	A list field that wraps a standard `Field`, allowing multiple instances of the field to be stored as a list in the database.
`name`
`STRICT`
`component_id`	A unicode string field.
`field_names`	An ordered tuple of the public fields of this document.

Methods:

`clean`()	Hook for doing document level data cleaning (usually validation or assignment) before validation is run.
`clear_field`(field_name)	Clears the field from the document.
`copy`()	Returns a deep copy of the document.
`fancy_repr`([class_name, select_fields, ...])	Generates a customizable string representation of the document.
`field_to_mongo`(field_name)
`field_to_python`(field_name, value)
`from_dict`(d[, extended])	Loads the document from a BSON/JSON dictionary.
`from_json`(s)	Loads the document from a JSON string.
`get_field`(field_name)	Gets the field of the document.
`get_text_score`()	Get text score from text query
`has_field`(field_name)	Determines whether the document has a field of the given name.
`iter_fields`()	Returns an iterator over the `(name, value)` pairs of the public fields of the document.
`merge`(doc[, merge_lists, merge_dicts, overwrite])	Merges the contents of the given document into this document.
`set_field`(field_name, value[, create])	Sets the value of a field of the document.
`to_dict`([extended])	Serializes this document to a BSON/JSON dictionary.
`to_json`([pretty_print])	Serializes the document to a JSON string.
`to_mongo`(args, *kwargs)	Return as SON data ready for use with MongoDB.
`validate`([clean])	Ensure that all fields' values are valid and that required fields are present.

Classes:

my_metaclass

alias of DocumentMetaclass

children#

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
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

orientation#

A unicode string field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

active_child#

A unicode string field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

sizes#

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
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

property name#

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

component_id#

A unicode string field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

copy()#

Returns a deep copy of the document.

Returns:: a SerializableDocument

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

Generates a customizable string representation of the document.

Parameters:

class_name (None) – optional class name to use
select_fields (None) – iterable of field names to restrict to
exclude_fields (None) – iterable of field names to exclude
**kwargs – additional key-value pairs to include in the string representation

Returns:

a string representation of the document

property field_names#: An ordered tuple of the public fields of this document.

field_to_mongo(field_name)#

field_to_python(field_name, value)#

classmethod from_dict(d, extended=False)#

Loads the document from a BSON/JSON dictionary.

Parameters:

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

Returns:

a SerializableDocument

classmethod from_json(s)#

Loads the document from a JSON string.

Returns:: a SerializableDocument

get_field(field_name)#

Gets the field of the document.

Parameters:: field_name – the field name
Returns:: the field value
Raises:: AttributeError – if the field does not exist

get_text_score()#: Get text score from text query

has_field(field_name)#

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

Parameters:: field_name – the field name
Returns:: True/False

iter_fields()#

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

Returns:: an iterator that emits (name, value) tuples

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

Merges the contents of the given document into this document.

Parameters:

doc – a SerializableDocument of same type as this document
merge_lists (True) – whether to merge the elements of top-level list fields rather than treating the list as a single value
merge_dicts (True) – whether to recursively merge the contents of top-level dict fields rather than treating the dict as a single value
overwrite (True) – whether to overwrite (True) or skip (False) existing fields

my_metaclass#: alias of DocumentMetaclass

set_field(field_name, value, create=True)#

Sets the value of a field of the document.

Parameters:

field_name – the field name
value – the field value
create (True) – whether to create the field if it does not exist

Raises:

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

to_dict(extended=False)#

Serializes this document to a BSON/JSON dictionary.

Parameters:: extended (False) – whether to serialize extended JSON constructs such as ObjectIDs, Binary, etc. into JSON format
Returns:: a dict

to_json(pretty_print=False)#

Serializes the document to a JSON string.

Parameters:: pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations
Returns:: a JSON string

to_mongo(*args, **kwargs)#: Return as SON data ready for use with MongoDB.

validate(clean=True)#

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

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

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

Bases: Document

Document for configuration of a saved workspace in the App.

Contains a single Space as a child, which can in turn contain multiple children.

Attributes:

`child`	A field that stores instances of a given type of `fiftyone.core.odm.BaseEmbeddedDocument` object.
`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.
`last_loaded_at`	A datetime field.
`last_modified_at`	A datetime field.
`slug`	A unicode string field.
`STRICT`
`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.
`name`
`pk`	Get the primary key.

Miscellaneous:

`DoesNotExist`
`MultipleObjectsReturned`

Methods:

`cascade_save`(**kwargs)	Recursively save any references and generic references on the document.
`clean`()	Hook for doing document level data cleaning (usually validation or assignment) before validation is run.
`clear_field`(field_name)	Clears the field from the document.
`compare_indexes`()	Compares the indexes defined in MongoEngine with the ones existing in the database.
`copy`([new_id])	Returns a deep copy of the document.
`copy_with_new_id`()
`create_index`(keys[, background])	Creates the given indexes if required.
`delete`([signal_kwargs])	Delete the `Document` from the database.
`drop_collection`()	Drops the entire collection associated with this `Document` type from the database.
`ensure_indexes`()	Checks the document meta data and ensures all the indexes exist.
`fancy_repr`([class_name, select_fields, ...])	Generates a customizable string representation of the document.
`field_to_mongo`(field_name)
`field_to_python`(field_name, value)
`from_dict`(d[, extended])	Loads the document from a BSON/JSON dictionary.
`from_json`(s)	Loads the document from a JSON string.
`get_field`(field_name)	Gets the field of the document.
`get_text_score`()	Get text score from text query
`has_field`(field_name)	Determines whether the document has a field of the given name.
`iter_fields`()	Returns an iterator over the `(name, value)` pairs of the public fields of the document.
`list_indexes`()	Lists all indexes that should be created for the Document collection.
`merge`(doc[, merge_lists, merge_dicts, overwrite])	Merges the contents of the given document into this document.
`modify`([query])	Perform an atomic update of the document in the database and reload the document object using updated version.
`register_delete_rule`(document_cls, ...)	This method registers the delete rules to apply when removing this object.
`reload`(fields, *kwargs)	Reloads the document from the database.
`save`([upsert, validate, 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.
`to_dbref`()	Returns an instance of `DBRef` useful in __raw__ queries.
`to_dict`([extended])	Serializes this document to a BSON/JSON dictionary.
`to_json`([pretty_print])	Serializes the document to a JSON string.
`to_mongo`(args, *kwargs)	Return as SON data ready for use with MongoDB.
`update`(**kwargs)	Performs an update on the `Document` A convenience wrapper to `update()`.
`validate`([clean])	Ensure that all fields' values are valid and that required fields are present.

Classes:

my_metaclass

alias of TopLevelDocumentMetaclass

child#

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

Parameters:

document_type – the fiftyone.core.odm.BaseEmbeddedDocument type stored in this field
description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

color#

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

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

created_at#

A datetime field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

dataset_id#

An Object ID field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

description#

A unicode string field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

last_loaded_at#

A datetime field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

last_modified_at#

A datetime field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

slug#

A unicode string field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

exception DoesNotExist#

Bases: DoesNotExist

Methods:

`add_note`	Exception.add_note(note) -- add a note to the exception
`with_traceback`	Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

Attributes:

args

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

args#

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

exception MultipleObjectsReturned#

Bases: MultipleObjectsReturned

Methods:

`add_note`	Exception.add_note(note) -- add a note to the exception
`with_traceback`	Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

Attributes:

args

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

args#

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

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(new_id=False)#

Returns a deep copy of the document.

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

copy_with_new_id()#

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

Creates the given indexes if required.

Parameters:

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

delete(signal_kwargs=None, **write_concern)#

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

Parameters:

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

classmethod drop_collection()#

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

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

classmethod ensure_indexes()#

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

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

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

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

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

Note

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

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

Generates a customizable string representation of the document.

Parameters:

class_name (None) – optional class name to use
select_fields (None) – iterable of field names to restrict to
exclude_fields (None) – iterable of field names to exclude
**kwargs – additional key-value pairs to include in the string representation

Returns:

a string representation of the document

property field_names#: An ordered tuple of the public fields of this document.

field_to_mongo(field_name)#

field_to_python(field_name, value)#

classmethod from_dict(d, extended=False)#

Loads the document from a BSON/JSON dictionary.

Parameters:

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

Returns:

a SerializableDocument

classmethod from_json(s)#

Loads the document from a JSON string.

Returns:: a SerializableDocument

get_field(field_name)#

Gets the field of the document.

Parameters:: field_name – the field name
Returns:: the field value
Raises:: AttributeError – if the field does not exist

get_text_score()#: Get text score from text query

has_field(field_name)#

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

Parameters:: field_name – the field name
Returns:: True/False

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 TopLevelDocumentMetaclass

property name#

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 the document from the database.

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

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

Saves the document to the database.

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

Parameters:

upsert (False) – whether to insert the document if it has an id populated but no document with that ID exists in the database
validate (True) – whether to validate the document
safe (False) – whether to reload() the document before raising any errors

Returns:

self

select_related(max_depth=1)#: Handles dereferencing of DBRef objects to a maximum depth in order to cut down the number queries to mongodb.

set_field(field_name, value, create=True)#

Sets the value of a field of the document.

Parameters:

field_name – the field name
value – the field value
create (True) – whether to create the field if it does not exist

Raises:

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

switch_collection(collection_name, keep_created=True)#

Temporarily switch the collection for a document instance.

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

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

Parameters:

collection_name (str) – The database alias to use for saving the document
keep_created (bool) – keep self._created value after switching collection, else is reset to True

See also

Use switch_db if you need to read from another database

switch_db(db_alias, keep_created=True)#

Temporarily switch the database for a document instance.

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

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

Parameters:

db_alias (str) – The database alias to use for saving the document
keep_created (bool) – keep self._created value after switching db, else is reset to True

See also

Use switch_collection if you need to read from another collection

to_dbref()#: Returns an instance of DBRef useful in __raw__ queries.

to_dict(extended=False)#

Serializes this document to a BSON/JSON dictionary.

Parameters:: extended (False) – whether to serialize extended JSON constructs such as ObjectIDs, Binary, etc. into JSON format
Returns:: a dict

to_json(pretty_print=False)#

Serializes the document to a JSON string.

Parameters:: pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations
Returns:: a JSON string

to_mongo(*args, **kwargs)#: Return as SON data ready for use with MongoDB.

update(**kwargs)#

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

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

validate(clean=True)#

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

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