<!-- # hard line break macro for HTML -->

# fiftyone.core.odm.utils

Utilities for documents.

Copyright 2017-2026, Voxel51, Inc.
<br/>
[voxel51.com](https://voxel51.com/)
<br/>
<br/>

**Functions:**

| [`serialize_value`](#fiftyone.core.odm.utils.serialize_value)(value[, extended])                  | Serializes the given value.                                                                                              |
|---------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------|
| [`deserialize_value`](#fiftyone.core.odm.utils.deserialize_value)(value)                          | Deserializes the given value.                                                                                            |
| [`validate_field_name`](#fiftyone.core.odm.utils.validate_field_name)(field_name[, ...])          | Verifies that the given field name is valid.                                                                             |
| [`warn_reserved_pk_paths`](#fiftyone.core.odm.utils.warn_reserved_pk_paths)(paths)                | Warns once if any of the given field paths contain a component named `"pk"`, which is a reserved keyword in MongoEngine. |
| [`create_field`](#fiftyone.core.odm.utils.create_field)(name, ftype[, ...])                       | Creates the field defined by the given specification.                                                                    |
| [`create_implied_field`](#fiftyone.core.odm.utils.create_implied_field)(path, value[, dynamic])   | Creates the field for the given value.                                                                                   |
| [`get_field_kwargs`](#fiftyone.core.odm.utils.get_field_kwargs)(field)                            | Constructs the field keyword arguments dictionary for the given field.                                                   |
| [`get_implied_field_kwargs`](#fiftyone.core.odm.utils.get_implied_field_kwargs)(value[, dynamic]) | Infers the field keyword arguments dictionary for a field that can hold the given value.                                 |
| [`validate_fields_match`](#fiftyone.core.odm.utils.validate_fields_match)(name, field, ...)       | Validates that the types of the given fields match.                                                                      |
| [`load_dataset`](#fiftyone.core.odm.utils.load_dataset)(\*args, \*\*kwargs)                       |                                                                                                                          |

**Classes:**

| [`DocumentRegistry`](#fiftyone.core.odm.utils.DocumentRegistry)()   | A registry of [`fiftyone.core.odm.document.MongoEngineBaseDocument`](fiftyone.core.odm.document.md#fiftyone.core.odm.document.MongoEngineBaseDocument) classes found when importing data from the database.   |
|---------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

**Exceptions:**

| [`DocumentRegistryError`](#fiftyone.core.odm.utils.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.warn_reserved_pk_paths(paths)

Warns once if any of the given field paths contain a component named
`"pk"`, which is a reserved keyword in MongoEngine.

* **Parameters:**
  **paths** – an iterable of field paths

### 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`](fiftyone.core.odm.dataset.md#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`](fiftyone.core.fields.md#fiftyone.core.fields.Field)
  * **embedded_doc_type** (*None*) – the
    [`fiftyone.core.odm.BaseEmbeddedDocument`](fiftyone.core.odm.md#fiftyone.core.odm.BaseEmbeddedDocument) type of the field.
    Only applicable when `ftype` is
    [`fiftyone.core.fields.EmbeddedDocumentField`](fiftyone.core.fields.md#fiftyone.core.fields.EmbeddedDocumentField)
  * **subfield** (*None*) – the [`fiftyone.core.fields.Field`](fiftyone.core.fields.md#fiftyone.core.fields.Field) type of the
    contained field. Only applicable when `ftype` is
    [`fiftyone.core.fields.ListField`](fiftyone.core.fields.md#fiftyone.core.fields.ListField) or
    [`fiftyone.core.fields.DictField`](fiftyone.core.fields.md#fiftyone.core.fields.DictField)
  * **fields** (*None*) – a list of [`fiftyone.core.fields.Field`](fiftyone.core.fields.md#fiftyone.core.fields.Field) instances
    defining embedded document attributes. Only applicable when
    `ftype` is [`fiftyone.core.fields.EmbeddedDocumentField`](fiftyone.core.fields.md#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.fields.md#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.fields.md#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`](fiftyone.core.fields.md#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`](fiftyone.core.fields.md#fiftyone.core.fields.Field)
  * **existing_field** – the reference [`fiftyone.core.fields.Field`](fiftyone.core.fields.md#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`](fiftyone.core.odm.document.md#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`](#fiftyone.core.odm.utils.DocumentRegistryError.add_note)(object, /)             | Exception.add_note(note) -- add a note to the exception                         |
|----------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------|
| [`with_traceback`](#fiftyone.core.odm.utils.DocumentRegistryError.with_traceback)(object, /) | Exception.with_traceback(tb) -- set self._\_traceback_\_ to tb and return self. |

**Attributes:**

| [`args`](#fiftyone.core.odm.utils.DocumentRegistryError.args)   |    |
|-----------------------------------------------------------------|----|

#### add_note(object,)

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

#### args

#### with_traceback(object,)

Exception.with_traceback(tb) –
set self._\_traceback_\_ to tb and return self.

### fiftyone.core.odm.utils.load_dataset(\*args, \*\*kwargs)