fiftyone.core.odm.mixins

Mixins and helpers for dataset backing documents.

Copyright 2017-2025, Voxel51, Inc.

voxel51.com

Functions:

get_default_fields(cls[, include_private, …])

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

Classes:

DatasetMixin()	Mixin interface for fiftyone.core.odm.document.Document subclasses that are backed by a dataset.
NoDatasetMixin()	Mixin for fiftyone.core.odm.document.SerializableDocument subtypes that are not backed by a dataset.

fiftyone.core.odm.mixins.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.mixins.DatasetMixin

Bases: object

Mixin interface for fiftyone.core.odm.document.Document subclasses that are backed by a dataset.

Attributes:

collection_name
field_names

Methods:

get_field(field_name)
set_field(field_name, value[, create, …])
clear_field(field_name)
get_field_schema([ftype, embedded_doc_type, …])	Returns a schema dictionary describing the fields of this document.
merge_field_schema(schema[, expand_schema, …])	Merges the field schema into this document.
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.

property collection_name

property field_names

get_field(field_name)

set_field(field_name, value, create=True, validate=True, dynamic=False, _enforce_read_only=True)

clear_field(field_name)

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

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

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

class fiftyone.core.odm.mixins.NoDatasetMixin

Bases: object

Mixin for fiftyone.core.odm.document.SerializableDocument subtypes that are not backed by a dataset.

Attributes:

field_names
in_db

Methods:

has_field(field_name)
get_field(field_name)
set_field(field_name, value[, create, …])
clear_field(field_name)
to_dict([extended])
from_dict(d[, extended])
save()
reload()
delete()

property field_names

property in_db

has_field(field_name)

get_field(field_name)

set_field(field_name, value, create=True, validate=True, dynamic=False)

clear_field(field_name)

to_dict(extended=False)

classmethod from_dict(d, extended=False)

save()

reload()

delete()