fiftyone.core.odm.utils#

Utilities for documents.

Copyright 2017-2025, Voxel51, Inc.

Functions:

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.

load_dataset([id, name])

Loads the dataset from the database by its unique id or name.

Classes:

DocumentRegistry()

A registry of fiftyone.core.odm.document.MongoEngineBaseDocument classes found when importing data from the database.

Exceptions:

DocumentRegistryError

Error raised when an unknown document class is encountered.

fiftyone.core.odm.utils.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.utils.deserialize_value(value)#

Deserializes the given value.

Parameters:

value – the serialized value

Returns:

the value

fiftyone.core.odm.utils.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.utils.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:
Returns:

a fiftyone.core.fields.Field

fiftyone.core.odm.utils.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.utils.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.utils.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.utils.validate_fields_match(name, field, existing_field)#

Validates that the types of the given fields match.

Embedded document fields are not validated, if applicable.

Parameters:
Raises:

ValueError – if the fields do not match

class fiftyone.core.odm.utils.DocumentRegistry#

Bases: object

A registry of fiftyone.core.odm.document.MongoEngineBaseDocument classes found when importing data from the database.

exception fiftyone.core.odm.utils.DocumentRegistryError#

Bases: Exception

Error raised when an unknown document class is encountered.

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:

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.

fiftyone.core.odm.utils.load_dataset(id=None, name=None)#

Loads the dataset from the database by its unique id or name. Throws an error if neither id nor name is provided.

Parameters:
  • id (None) – the unique id of the dataset

  • name (None) – the name of the dataset

Returns:

a fiftyone.core.dataset.Dataset