fiftyone.core.odm.ontology#

Ontology documents.

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

Classes:

`OntologyType`(value)	Allowed values for `OntologyDocument.type` in storage and APIs.
`OntologyDocument`(**kwargs)	Backing document for ontologies.

class fiftyone.core.odm.ontology.OntologyType(value)#

Bases: str, Enum

Allowed values for OntologyDocument.type in storage and APIs.

TAXONOMY — a reusable hierarchical class tree. Multiple annotation ontologies can reference the same taxonomy by name.

ANNOTATION_ONTOLOGY — a container that defines classes, attributes (with optional conditional display logic), and references to taxonomies. This is the document that gets connected to a label schema on a field.

Attributes:

`TAXONOMY`
`ANNOTATION_ONTOLOGY`

Methods:

`encode`([encoding, errors])	Encode the string using the codec registered for encoding.
`replace`(old, new[, count])	Return a copy with all occurrences of substring old replaced by new.
`split`([sep, maxsplit])	Return a list of the substrings in the string, using sep as the separator string.
`rsplit`([sep, maxsplit])	Return a list of the substrings in the string, using sep as the separator string.
`join`(iterable, /)	Concatenate any number of strings.
`capitalize`()	Return a capitalized version of the string.
`casefold`()	Return a version of the string suitable for caseless comparisons.
`title`()	Return a version of the string where each word is titlecased.
`center`(width[, fillchar])	Return a centered string of length width.
`count`(sub[, start[, end]])	Return the number of non-overlapping occurrences of substring sub in string S[start:end].
`expandtabs`([tabsize])	Return a copy where all tab characters are expanded using spaces.
`find`(sub[, start[, end]])	Return the lowest index in S where substring sub is found, such that sub is contained within S[start:end].
`partition`(sep, /)	Partition the string into three parts using the given separator.
`index`(sub[, start[, end]])	Return the lowest index in S where substring sub is found, such that sub is contained within S[start:end].
`ljust`(width[, fillchar])	Return a left-justified string of length width.
`lower`()	Return a copy of the string converted to lowercase.
`lstrip`([chars])	Return a copy of the string with leading whitespace removed.
`rfind`(sub[, start[, end]])	Return the highest index in S where substring sub is found, such that sub is contained within S[start:end].
`rindex`(sub[, start[, end]])	Return the highest index in S where substring sub is found, such that sub is contained within S[start:end].
`rjust`(width[, fillchar])	Return a right-justified string of length width.
`rstrip`([chars])	Return a copy of the string with trailing whitespace removed.
`rpartition`(sep, /)	Partition the string into three parts using the given separator.
`splitlines`([keepends])	Return a list of the lines in the string, breaking at line boundaries.
`strip`([chars])	Return a copy of the string with leading and trailing whitespace removed.
`swapcase`()	Convert uppercase characters to lowercase and lowercase characters to uppercase.
`translate`(table, /)	Replace each character in the string using the given translation table.
`upper`()	Return a copy of the string converted to uppercase.
`startswith`(prefix[, start[, end]])	Return True if S starts with the specified prefix, False otherwise.
`endswith`(suffix[, start[, end]])	Return True if S ends with the specified suffix, False otherwise.
`removeprefix`(prefix, /)	Return a str with the given prefix string removed if present.
`removesuffix`(suffix, /)	Return a str with the given suffix string removed if present.
`isascii`()	Return True if all characters in the string are ASCII, False otherwise.
`islower`()	Return True if the string is a lowercase string, False otherwise.
`isupper`()	Return True if the string is an uppercase string, False otherwise.
`istitle`()	Return True if the string is a title-cased string, False otherwise.
`isspace`()	Return True if the string is a whitespace string, False otherwise.
`isdecimal`()	Return True if the string is a decimal string, False otherwise.
`isdigit`()	Return True if the string is a digit string, False otherwise.
`isnumeric`()	Return True if the string is a numeric string, False otherwise.
`isalpha`()	Return True if the string is an alphabetic string, False otherwise.
`isalnum`()	Return True if the string is an alpha-numeric string, False otherwise.
`isidentifier`()	Return True if the string is a valid Python identifier, False otherwise.
`isprintable`()	Return True if the string is printable, False otherwise.
`zfill`(width, /)	Pad a numeric string with zeros on the left, to fill a field of the given width.
`format`(args, *kwargs)	Return a formatted version of S, using substitutions from args and kwargs.
`format_map`(mapping)	Return a formatted version of S, using substitutions from mapping.
`maketrans`	Return a translation table usable for str.translate().

TAXONOMY = 'taxonomy'#

ANNOTATION_ONTOLOGY = 'annotation_ontology'#

encode(encoding='utf-8', errors='strict')#

Encode the string using the codec registered for encoding.

encoding: The encoding in which to encode the string.
errors: The error handling scheme to use for encoding errors. The default is ‘strict’ meaning that encoding errors raise a UnicodeEncodeError. Other possible values are ‘ignore’, ‘replace’ and ‘xmlcharrefreplace’ as well as any other name registered with codecs.register_error that can handle UnicodeEncodeErrors.

replace(old, new, count=-1, /)#

Return a copy with all occurrences of substring old replaced by new.

count
Maximum number of occurrences to replace. -1 (the default value) means replace all occurrences.

If the optional argument count is given, only the first count occurrences are replaced.

split(sep=None, maxsplit=-1)#

Return a list of the substrings in the string, using sep as the separator string.

sep
The separator used to split the string.

When set to None (the default value), will split on any whitespace character (including n r t f and spaces) and will discard empty strings from the result.

maxsplit
Maximum number of splits. -1 (the default value) means no limit.

Splitting starts at the front of the string and works to the end.

Note, str.split() is mainly useful for data that has been intentionally delimited. With natural text that includes punctuation, consider using the regular expression module.

rsplit(sep=None, maxsplit=-1)#

Return a list of the substrings in the string, using sep as the separator string.

sep
The separator used to split the string.

When set to None (the default value), will split on any whitespace character (including n r t f and spaces) and will discard empty strings from the result.

maxsplit
Maximum number of splits. -1 (the default value) means no limit.

Splitting starts at the end of the string and works to the front.

join(iterable, /)#

Concatenate any number of strings.

The string whose method is called is inserted in between each given string. The result is returned as a new string.

Example: ‘.’.join([‘ab’, ‘pq’, ‘rs’]) -> ‘ab.pq.rs’

capitalize()#

Return a capitalized version of the string.

More specifically, make the first character have upper case and the rest lower case.

casefold()#: Return a version of the string suitable for caseless comparisons.

title()#

Return a version of the string where each word is titlecased.

More specifically, words start with uppercased characters and all remaining cased characters have lower case.

center(width, fillchar=' ', /)#

Return a centered string of length width.

Padding is done using the specified fill character (default is a space).

count(sub[, start[, end]]) → int#: Return the number of non-overlapping occurrences of substring sub in string S[start:end]. Optional arguments start and end are interpreted as in slice notation.

expandtabs(tabsize=8)#

Return a copy where all tab characters are expanded using spaces.

If tabsize is not given, a tab size of 8 characters is assumed.

find(sub[, start[, end]]) → int#

Return the lowest index in S where substring sub is found, such that sub is contained within S[start:end]. Optional arguments start and end are interpreted as in slice notation.

Return -1 on failure.

partition(sep, /)#

Partition the string into three parts using the given separator.

This will search for the separator in the string. If the separator is found, returns a 3-tuple containing the part before the separator, the separator itself, and the part after it.

If the separator is not found, returns a 3-tuple containing the original string and two empty strings.

index(sub[, start[, end]]) → int#

Return the lowest index in S where substring sub is found, such that sub is contained within S[start:end]. Optional arguments start and end are interpreted as in slice notation.

Raises ValueError when the substring is not found.

ljust(width, fillchar=' ', /)#

Return a left-justified string of length width.

Padding is done using the specified fill character (default is a space).

lower()#: Return a copy of the string converted to lowercase.

lstrip(chars=None, /)#

Return a copy of the string with leading whitespace removed.

If chars is given and not None, remove characters in chars instead.

rfind(sub[, start[, end]]) → int#

Return the highest index in S where substring sub is found, such that sub is contained within S[start:end]. Optional arguments start and end are interpreted as in slice notation.

Return -1 on failure.

rindex(sub[, start[, end]]) → int#

Return the highest index in S where substring sub is found, such that sub is contained within S[start:end]. Optional arguments start and end are interpreted as in slice notation.

Raises ValueError when the substring is not found.

rjust(width, fillchar=' ', /)#

Return a right-justified string of length width.

Padding is done using the specified fill character (default is a space).

rstrip(chars=None, /)#

Return a copy of the string with trailing whitespace removed.

If chars is given and not None, remove characters in chars instead.

rpartition(sep, /)#

Partition the string into three parts using the given separator.

This will search for the separator in the string, starting at the end. If the separator is found, returns a 3-tuple containing the part before the separator, the separator itself, and the part after it.

If the separator is not found, returns a 3-tuple containing two empty strings and the original string.

splitlines(keepends=False)#

Return a list of the lines in the string, breaking at line boundaries.

Line breaks are not included in the resulting list unless keepends is given and true.

strip(chars=None, /)#

Return a copy of the string with leading and trailing whitespace removed.

If chars is given and not None, remove characters in chars instead.

swapcase()#: Convert uppercase characters to lowercase and lowercase characters to uppercase.

translate(table, /)#

Replace each character in the string using the given translation table.

table
Translation table, which must be a mapping of Unicode ordinals to Unicode ordinals, strings, or None.

The table must implement lookup/indexing via __getitem__, for instance a dictionary or list. If this operation raises LookupError, the character is left untouched. Characters mapped to None are deleted.

upper()#: Return a copy of the string converted to uppercase.

startswith(prefix[, start[, end]]) → bool#: Return True if S starts with the specified prefix, False otherwise. With optional start, test S beginning at that position. With optional end, stop comparing S at that position. prefix can also be a tuple of strings to try.

endswith(suffix[, start[, end]]) → bool#: Return True if S ends with the specified suffix, False otherwise. With optional start, test S beginning at that position. With optional end, stop comparing S at that position. suffix can also be a tuple of strings to try.

removeprefix(prefix, /)#

Return a str with the given prefix string removed if present.

If the string starts with the prefix string, return string[len(prefix):]. Otherwise, return a copy of the original string.

removesuffix(suffix, /)#

Return a str with the given suffix string removed if present.

If the string ends with the suffix string and that suffix is not empty, return string[:-len(suffix)]. Otherwise, return a copy of the original string.

isascii()#

Return True if all characters in the string are ASCII, False otherwise.

ASCII characters have code points in the range U+0000-U+007F. Empty string is ASCII too.

islower()#

Return True if the string is a lowercase string, False otherwise.

A string is lowercase if all cased characters in the string are lowercase and there is at least one cased character in the string.

isupper()#

Return True if the string is an uppercase string, False otherwise.

A string is uppercase if all cased characters in the string are uppercase and there is at least one cased character in the string.

istitle()#

Return True if the string is a title-cased string, False otherwise.

In a title-cased string, upper- and title-case characters may only follow uncased characters and lowercase characters only cased ones.

isspace()#

Return True if the string is a whitespace string, False otherwise.

A string is whitespace if all characters in the string are whitespace and there is at least one character in the string.

isdecimal()#

Return True if the string is a decimal string, False otherwise.

A string is a decimal string if all characters in the string are decimal and there is at least one character in the string.

isdigit()#

Return True if the string is a digit string, False otherwise.

A string is a digit string if all characters in the string are digits and there is at least one character in the string.

isnumeric()#

Return True if the string is a numeric string, False otherwise.

A string is numeric if all characters in the string are numeric and there is at least one character in the string.

isalpha()#

Return True if the string is an alphabetic string, False otherwise.

A string is alphabetic if all characters in the string are alphabetic and there is at least one character in the string.

isalnum()#

Return True if the string is an alpha-numeric string, False otherwise.

A string is alpha-numeric if all characters in the string are alpha-numeric and there is at least one character in the string.

isidentifier()#

Return True if the string is a valid Python identifier, False otherwise.

Call keyword.iskeyword(s) to test whether string s is a reserved identifier, such as “def” or “class”.

isprintable()#

Return True if the string is printable, False otherwise.

A string is printable if all of its characters are considered printable in repr() or if it is empty.

zfill(width, /)#

Pad a numeric string with zeros on the left, to fill a field of the given width.

The string is never truncated.

format(*args, **kwargs) → str#: Return a formatted version of S, using substitutions from args and kwargs. The substitutions are identified by braces (‘{’ and ‘}’).

format_map(mapping) → str#: Return a formatted version of S, using substitutions from mapping. The substitutions are identified by braces (‘{’ and ‘}’).

static maketrans()#

Return a translation table usable for str.translate().

If there is only one argument, it must be a dictionary mapping Unicode ordinals (integers) or characters to Unicode ordinals, strings or None. Character keys will be then converted to ordinals. If there are two arguments, they must be strings of equal length, and in the resulting dictionary, each character in x will be mapped to the character at the same position in y. If there is a third argument, it must be a string, whose characters will be mapped to None in the result.

class fiftyone.core.odm.ontology.OntologyDocument(**kwargs)#

Bases: Document

Backing document for ontologies.

Ontologies are global resources not scoped to any single dataset. Multiple datasets can reference the same ontology by name. Each save creates a new versioned document; (slug, version) is unique, so names differing only in case or punctuation collide on save.

Attributes:

`name`	A unicode string field.
`slug`	A unicode string field.
`version`	A 32 bit integer field.
`type`	A unicode string field.
`description`	A unicode string field.
`root`	A dictionary field that wraps a standard Python dictionary.
`created_at`	A datetime field.
`last_modified_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.

Methods:

`save`(args, *kwargs)	Saves the document to the database.
`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.
`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.

Miscellaneous:

`DoesNotExist`
`MultipleObjectsReturned`

Classes:

my_metaclass

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

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

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

root#

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

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

save(*args, **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

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

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