fiftyone.core.odm.utils

Utilities for documents.

Copyright 2017-2025, Voxel51, Inc.

voxel51.com

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

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

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

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