# fiftyone.core.sample
Dataset samples.
Copyright 2017-2026, Voxel51, Inc.
[voxel51.com](https://voxel51.com/)
**Functions:**
| [`get_default_sample_fields`](#fiftyone.core.sample.get_default_sample_fields)([include_private, ...]) | Returns the default fields present on all samples. |
|----------------------------------------------------------------------------------------------------------|------------------------------------------------------|
**Classes:**
| [`Sample`](#fiftyone.core.sample.Sample)([filepath, tags, metadata, ...]) | A sample in a [`fiftyone.core.dataset.Dataset`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset). |
|-------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------|
| [`SampleView`](#fiftyone.core.sample.SampleView)(doc, view[, selected_fields, ...]) | A view into a [`Sample`](#fiftyone.core.sample.Sample) in a dataset. |
### fiftyone.core.sample.get_default_sample_fields(include_private=False, use_db_fields=False)
Returns the default fields present on all samples.
* **Parameters:**
* **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.sample.Sample(filepath=None, tags=None, metadata=None, media_reference=None, \*\*kwargs)
Bases: `_SampleMixin`, [`Document`](fiftyone.core.document.md#fiftyone.core.document.Document)
A sample in a [`fiftyone.core.dataset.Dataset`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset).
Samples store all information associated with a particular piece of data in
a dataset, including basic metadata about the data, one or more sets of
labels (ground truth, user-provided, or FiftyOne-generated), and additional
features associated with subsets of the data and/or label sets.
#### NOTE
[`Sample`](#fiftyone.core.sample.Sample) instances that are **in datasets** are singletons,
i.e., `dataset[sample_id]` will always return the same
[`Sample`](#fiftyone.core.sample.Sample) instance.
* **Parameters:**
* **filepath** (*None*) – the path to the data on disk for a filepath-backed
sample. The path is converted to an absolute path (if necessary)
via [`fiftyone.core.storage.normalize_path()`](fiftyone.core.storage.md#fiftyone.core.storage.normalize_path)
* **media_reference** (*None*) – an immutable
[`fiftyone.core.media_reference.MediaReference`](fiftyone.core.media_reference.md#fiftyone.core.media_reference.MediaReference) for a
reference-backed sample
* **tags** (*None*) – a list of tags for the sample
* **metadata** (*None*) – a [`fiftyone.core.metadata.Metadata`](fiftyone.core.metadata.md#fiftyone.core.metadata.Metadata) instance
* **\*\*kwargs** – additional fields to dynamically set on the sample
**Methods:**
| [`reload`](#fiftyone.core.sample.Sample.reload)([hard, include_frames]) | Reloads the sample from the database. |
|--------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
| [`save`](#fiftyone.core.sample.Sample.save)() | Saves the sample to the database. |
| [`from_frame`](#fiftyone.core.sample.Sample.from_frame)(frame[, filepath]) | Creates a sample from the given frame. |
| [`from_doc`](#fiftyone.core.sample.Sample.from_doc)(doc[, dataset]) | Creates a sample backed by the given document. |
| [`from_dict`](#fiftyone.core.sample.Sample.from_dict)(d) | Loads the sample from a JSON dictionary. |
| [`add_labels`](#fiftyone.core.sample.Sample.add_labels)(labels[, label_field, ...]) | Adds the given labels to the sample. |
| [`clear_field`](#fiftyone.core.sample.Sample.clear_field)(field_name) | Clears the value of a field of the document. |
| [`compute_metadata`](#fiftyone.core.sample.Sample.compute_metadata)([overwrite, skip_failures]) | Populates the `metadata` field of the sample. |
| [`copy`](#fiftyone.core.sample.Sample.copy)([fields, omit_fields]) | Returns a deep copy of the sample that has not been added to the database. |
| [`from_json`](#fiftyone.core.sample.Sample.from_json)(s) | Loads the document from a JSON string. |
| [`get_field`](#fiftyone.core.sample.Sample.get_field)(field_name) | Gets the value of a field of the document. |
| [`get_media_key`](#fiftyone.core.sample.Sample.get_media_key)() | Returns the sample's active logical media key. |
| [`has_field`](#fiftyone.core.sample.Sample.has_field)(field_name) | Determines whether the document has the given field. |
| [`iter_fields`](#fiftyone.core.sample.Sample.iter_fields)([include_id, include_timestamps]) | Returns an iterator over the `(name, value)` pairs of the public fields of the document. |
| [`merge`](#fiftyone.core.sample.Sample.merge)(sample[, fields, omit_fields, ...]) | Merges the fields of the given sample into this sample. |
| [`set_field`](#fiftyone.core.sample.Sample.set_field)(field_name, value[, create, ...]) | Sets the value of a field of the document. |
| [`to_dict`](#fiftyone.core.sample.Sample.to_dict)([include_frames, include_private]) | Serializes the sample to a JSON dictionary. |
| [`to_json`](#fiftyone.core.sample.Sample.to_json)([pretty_print]) | Serializes the document to a JSON string. |
| [`to_mongo_dict`](#fiftyone.core.sample.Sample.to_mongo_dict)([include_id]) | Serializes the document to a BSON dictionary equivalent to the representation that would be stored in the database. |
| [`update_fields`](#fiftyone.core.sample.Sample.update_fields)(fields_dict[, expand_schema, ...]) | Sets the dictionary of fields on the document. |
**Attributes:**
| [`dataset`](#fiftyone.core.sample.Sample.dataset) | The dataset to which this document belongs, or `None` if it has not been added to a dataset. |
|-------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`dataset_id`](#fiftyone.core.sample.Sample.dataset_id) | |
| [`field_names`](#fiftyone.core.sample.Sample.field_names) | An ordered tuple of the public field names of this document. |
| [`filename`](#fiftyone.core.sample.Sample.filename) | The basename or logical display name of the sample's media. |
| [`in_dataset`](#fiftyone.core.sample.Sample.in_dataset) | Whether the document has been added to a dataset. |
| [`media_reference`](#fiftyone.core.sample.Sample.media_reference) | The sample's [`fiftyone.core.media_reference.MediaReference`](fiftyone.core.media_reference.md#fiftyone.core.media_reference.MediaReference), or None for a filepath-backed sample. |
| [`media_type`](#fiftyone.core.sample.Sample.media_type) | The media type of the sample. |
#### reload(hard=False, include_frames=True)
Reloads the sample from the database.
* **Parameters:**
* **hard** (*False*) – whether to reload the sample’s schema in addition to
its field values. This is necessary if new fields may have been
added to the dataset schema
* **include_frames** (*True*) – whether to reload any in-memory frames of
video samples
#### save()
Saves the sample to the database.
#### *classmethod* from_frame(frame, filepath=None)
Creates a sample from the given frame.
* **Parameters:**
* **frame** – a [`fiftyone.core.frame.Frame`](fiftyone.core.frame.md#fiftyone.core.frame.Frame)
* **filepath** (*None*) – the path to the corresponding image frame on disk,
if not available
* **Returns:**
a [`Sample`](#fiftyone.core.sample.Sample)
#### *classmethod* from_doc(doc, dataset=None)
Creates a sample backed by the given document.
* **Parameters:**
* **doc** – a [`fiftyone.core.odm.sample.DatasetSampleDocument`](fiftyone.core.odm.sample.md#fiftyone.core.odm.sample.DatasetSampleDocument) or
[`fiftyone.core.odm.sample.NoDatasetSampleDocument`](fiftyone.core.odm.sample.md#fiftyone.core.odm.sample.NoDatasetSampleDocument)
* **dataset** (*None*) – the [`fiftyone.core.dataset.Dataset`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset) that
the sample belongs to
* **Returns:**
a [`Sample`](#fiftyone.core.sample.Sample)
#### *classmethod* from_dict(d)
Loads the sample from a JSON dictionary.
The returned sample will not belong to a dataset.
* **Returns:**
a [`Sample`](#fiftyone.core.sample.Sample)
#### add_labels(labels, label_field=None, confidence_thresh=None, classes=None, expand_schema=True, validate=True, dynamic=False)
Adds the given labels to the sample.
The provided `labels` can be any of the following:
- A [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) instance, in which case the
labels are directly saved in the specified `label_field`
- A dict mapping keys to [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label)
instances. In this case, the labels are added as follows:
```default
for key, value in labels.items():
sample[label_key(key)] = value
```
- A dict mapping frame numbers to [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label)
instances. In this case, the provided labels are interpreted as
frame-level labels that should be added as follows:
```default
sample.frames.merge(
{
frame_number: {label_field: label}
for frame_number, label in labels.items()
}
)
```
- A dict mapping frame numbers to dicts mapping keys to
[`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) instances. In this case, the
provided labels are interpreted as frame-level labels that should
be added as follows:
```default
sample.frames.merge(
{
frame_number: {
label_key(key): value
for key, value in frame_dict.items()
}
for frame_number, frame_dict in labels.items()
}
)
```
In the above, the `label_key` function maps label dict keys to field
names, and is defined from `label_field` as follows:
```default
if isinstance(label_field, dict):
label_key = lambda k: label_field.get(k, k)
elif label_field is not None:
label_key = lambda k: label_field + "_" + k
else:
label_key = lambda k: k
```
* **Parameters:**
* **labels** – a [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) or dict of labels per
the description above
* **label_field** (*None*) – the sample field, prefix, or dict defining in
which field(s) to save the labels
* **confidence_thresh** (*None*) – an optional confidence threshold to apply
to any applicable labels before saving them
* **classes** (*None*) – an optional iterable of classes to which to
restrict any applicable labels generated by the model
* **expand_schema** (*True*) – whether to dynamically add new fields
encountered to the dataset schema. If False, an error is raised
if any fields are not in the dataset schema
* **validate** (*True*) – whether to validate values for existing fields
* **dynamic** (*False*) – whether to declare dynamic attributes
#### clear_field(field_name)
Clears the value of a field of the document.
* **Parameters:**
**field_name** – the name of the field to clear
* **Raises:**
**AttributeError** – if the field does not exist
#### compute_metadata(overwrite=False, skip_failures=False)
Populates the `metadata` field of the sample.
* **Parameters:**
* **overwrite** (*False*) – whether to overwrite existing metadata
* **skip_failures** (*False*) – whether to gracefully continue without
raising an error if metadata cannot be computed
#### copy(fields=None, omit_fields=None)
Returns a deep copy of the sample that has not been added to the
database.
* **Parameters:**
* **fields** (*None*) – an optional field or iterable of fields to which to
restrict the copy. This can also be a dict mapping existing
field names to new field names
* **omit_fields** (*None*) – an optional field or iterable of fields to
exclude from the copy
* **Returns:**
a [`Sample`](#fiftyone.core.sample.Sample)
#### *property* dataset
The dataset to which this document belongs, or `None` if it has
not been added to a dataset.
#### *property* dataset_id
#### *property* field_names
An ordered tuple of the public field names of this document.
#### *property* filename
The basename or logical display name of the sample’s media.
#### *classmethod* from_json(s)
Loads the document from a JSON string.
The returned document will not belong to a dataset.
* **Parameters:**
**s** – the JSON string
* **Returns:**
a `Document`
#### get_field(field_name)
Gets the value of a field of the document.
* **Parameters:**
**field_name** – the field name
* **Returns:**
the field value
* **Raises:**
**AttributeError** – if the field does not exist
#### get_media_key()
Returns the sample’s active logical media key.
Reference-backed samples return their reference’s key. All other
samples return their filepath.
#### has_field(field_name)
Determines whether the document has the given field.
* **Parameters:**
**field_name** – the field name
* **Returns:**
True/False
#### *property* in_dataset
Whether the document has been added to a dataset.
#### iter_fields(include_id=False, include_timestamps=False)
Returns an iterator over the `(name, value)` pairs of the public
fields of the document.
* **Parameters:**
* **include_id** (*False*) – whether to include the `id` field
* **include_timestamps** (*False*) – whether to include the `created_at`
and `last_modified_at` fields
* **Returns:**
an iterator that emits `(name, value)` tuples
#### *property* media_reference
The sample’s
[`fiftyone.core.media_reference.MediaReference`](fiftyone.core.media_reference.md#fiftyone.core.media_reference.MediaReference), or None for a filepath-backed sample.
The reference says which media source the sample’s media comes from
and where in it the sample is; the source itself is recorded once on
the dataset.
#### *property* media_type
The media type of the sample.
#### merge(sample, fields=None, omit_fields=None, merge_lists=True, merge_embedded_docs=False, overwrite=True, expand_schema=True, validate=True, dynamic=False)
Merges the fields of the given sample into this sample.
The behavior of this method is highly customizable. By default, all
top-level fields from the provided sample are merged in, overwriting
any existing values for those fields, with the exception of list fields
(e.g., `tags`) and label list fields (e.g.,
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) fields), in which case the
elements of the lists themselves are merged. In the case of label list
fields, labels with the same `id` in both samples are updated rather
than duplicated.
To avoid confusion between missing fields and fields whose value is
`None`, `None`-valued fields are always treated as missing while
merging.
This method can be configured in numerous ways, including:
- Whether new fields can be added to the dataset schema
- Whether list fields should be treated as ordinary fields and merged
as a whole rather than merging their elements
- Whether to merge only specific fields, or all but certain fields
- Mapping input sample fields to different field names of this sample
* **Parameters:**
* **sample** – a [`fiftyone.core.sample.Sample`](#fiftyone.core.sample.Sample)
* **fields** (*None*) – an optional field or iterable of fields to which to
restrict the merge. May contain frame fields for video samples.
This can also be a dict mapping field names of the input sample
to field names of this sample
* **omit_fields** (*None*) – an optional field or iterable of fields to
exclude from the merge. May contain frame fields for video
samples
* **merge_lists** (*True*) – whether to merge the elements of list fields
(e.g., `tags`) and label list fields (e.g.,
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) fields) rather than
merging the entire top-level field like other field types.
For label lists fields, existing
`fiftyone.core.label.Label` elements are either replaced
(when `overwrite` is True) or kept (when `overwrite` is
False) when their `id` matches a label from the provided
sample
* **merge_embedded_docs** (*False*) – whether to merge the attributes of
embedded documents (True) rather than merging the entire
top-level field (False)
* **overwrite** (*True*) – whether to overwrite (True) or skip (False)
existing fields and label elements
* **expand_schema** (*True*) – whether to dynamically add new fields
encountered to the dataset schema. If False, an error is raised
if any fields are not in the dataset schema
* **validate** (*True*) – whether to validate values for existing fields
* **dynamic** (*False*) – whether to declare dynamic embedded document
fields
#### set_field(field_name, value, create=True, validate=True, dynamic=False)
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
* **validate** (*True*) – whether to validate values for existing fields
* **dynamic** (*False*) – whether to declare dynamic embedded document
fields
* **Raises:**
* **ValueError** – if `field_name` is not an allowed field name
* **AttributeError** – if the field does not exist and `create == False`
#### to_dict(include_frames=False, include_private=False)
Serializes the sample to a JSON dictionary.
* **Parameters:**
* **include_frames** (*False*) – whether to include the frame labels for
video samples
* **include_private** (*False*) – whether to include private fields
* **Returns:**
a JSON dict
#### to_json(pretty_print=False)
Serializes the document to a JSON string.
The document ID and private fields are excluded in this representation.
* **Parameters:**
**pretty_print** (*False*) – whether to render the JSON in human readable
format with newlines and indentations
* **Returns:**
a JSON string
#### to_mongo_dict(include_id=False)
Serializes the document to a BSON dictionary equivalent to the
representation that would be stored in the database.
* **Parameters:**
**include_id** (*False*) – whether to include the document ID
* **Returns:**
a BSON dict
#### update_fields(fields_dict, expand_schema=True, validate=True, dynamic=False)
Sets the dictionary of fields on the document.
* **Parameters:**
* **fields_dict** – a dict mapping field names to values
* **expand_schema** (*True*) – whether to dynamically add new fields
encountered to the document schema. If False, an error is
raised if any fields are not in the document schema
* **validate** (*True*) – whether to validate values for existing fields
* **dynamic** (*False*) – whether to declare dynamic embedded document
fields
* **Raises:**
**AttributeError** – if `expand_schema == False` and a field does not
exist
### *class* fiftyone.core.sample.SampleView(doc, view, selected_fields=None, excluded_fields=None, filtered_fields=None)
Bases: `_SampleMixin`, [`DocumentView`](fiftyone.core.document.md#fiftyone.core.document.DocumentView)
A view into a [`Sample`](#fiftyone.core.sample.Sample) in a dataset.
Like [`Sample`](#fiftyone.core.sample.Sample) instances, the fields of a [`SampleView`](#fiftyone.core.sample.SampleView)
instance can be modified, new fields can be created, and any changes can be
saved to the database.
[`SampleView`](#fiftyone.core.sample.SampleView) instances differ from [`Sample`](#fiftyone.core.sample.Sample) instances in the
following ways:
- A sample view may contain only a subset of the fields of its source
sample, either by selecting and/or excluding specific fields
- A sample view may contain array fields or embedded array fields that
have been filtered, thus containing only a subset of the array elements
from the source sample
- Excluded fields of a sample view may not be accessed or modified
#### NOTE
Sample views should never be created manually; they are generated when
accessing the samples in a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView).
* **Parameters:**
* **doc** – a `fiftyone.core.odm.mixins.DatasetSampleDocument`
* **view** – the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) that the sample
belongs to
* **selected_fields** (*None*) – a set of field names that this sample view is
restricted to, if any
* **excluded_fields** (*None*) – a set of field names that are excluded from
this sample view, if any
* **filtered_fields** (*None*) – a set of field names of list fields that are
filtered in this sample view, if any
**Methods:**
| [`to_dict`](#fiftyone.core.sample.SampleView.to_dict)([include_frames, include_private]) | Serializes the sample view to a JSON dictionary. |
|------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
| [`save`](#fiftyone.core.sample.SampleView.save)() | Saves the sample view to the database. |
| [`add_labels`](#fiftyone.core.sample.SampleView.add_labels)(labels[, label_field, ...]) | Adds the given labels to the sample. |
| [`clear_field`](#fiftyone.core.sample.SampleView.clear_field)(field_name) | Clears the value of a field of the document. |
| [`compute_metadata`](#fiftyone.core.sample.SampleView.compute_metadata)([overwrite, skip_failures]) | Populates the `metadata` field of the sample. |
| [`copy`](#fiftyone.core.sample.SampleView.copy)([fields, omit_fields]) | Returns a deep copy of the sample that has not been added to the database. |
| [`get_field`](#fiftyone.core.sample.SampleView.get_field)(field_name) | Gets the value of a field of the document. |
| [`get_media_key`](#fiftyone.core.sample.SampleView.get_media_key)() | Returns the sample's active logical media key. |
| [`has_field`](#fiftyone.core.sample.SampleView.has_field)(field_name) | Determines whether the document has the given field. |
| [`iter_fields`](#fiftyone.core.sample.SampleView.iter_fields)([include_id, include_timestamps]) | Returns an iterator over the `(name, value)` pairs of the public fields of the document. |
| [`merge`](#fiftyone.core.sample.SampleView.merge)(sample[, fields, omit_fields, ...]) | Merges the fields of the given sample into this sample. |
| [`set_field`](#fiftyone.core.sample.SampleView.set_field)(field_name, value[, create, ...]) | Sets the value of a field of the document. |
| [`to_json`](#fiftyone.core.sample.SampleView.to_json)([pretty_print]) | Serializes the document to a JSON string. |
| [`to_mongo_dict`](#fiftyone.core.sample.SampleView.to_mongo_dict)([include_id]) | Serializes the document to a BSON dictionary equivalent to the representation that would be stored in the database. |
| [`update_fields`](#fiftyone.core.sample.SampleView.update_fields)(fields_dict[, expand_schema, ...]) | Sets the dictionary of fields on the document. |
**Attributes:**
| [`dataset`](#fiftyone.core.sample.SampleView.dataset) | The dataset to which this document belongs, or `None` if it has not been added to a dataset. |
|---------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`dataset_id`](#fiftyone.core.sample.SampleView.dataset_id) | |
| [`excluded_field_names`](#fiftyone.core.sample.SampleView.excluded_field_names) | The set of field names that are excluded on this document view, or `None` if no fields are explicitly excluded. |
| [`field_names`](#fiftyone.core.sample.SampleView.field_names) | An ordered tuple of field names of this document view. |
| [`filename`](#fiftyone.core.sample.SampleView.filename) | The basename or logical display name of the sample's media. |
| [`filtered_field_names`](#fiftyone.core.sample.SampleView.filtered_field_names) | The set of field names or `embedded.field.names` that have been filtered on this document view, or `None` if no fields are filtered. |
| [`in_dataset`](#fiftyone.core.sample.SampleView.in_dataset) | Whether the document has been added to a dataset. |
| [`media_reference`](#fiftyone.core.sample.SampleView.media_reference) | The sample's [`fiftyone.core.media_reference.MediaReference`](fiftyone.core.media_reference.md#fiftyone.core.media_reference.MediaReference), or None for a filepath-backed sample. |
| [`media_type`](#fiftyone.core.sample.SampleView.media_type) | The media type of the sample. |
| [`selected_field_names`](#fiftyone.core.sample.SampleView.selected_field_names) | The set of field names that are selected on this document view, or `None` if no fields are explicitly selected. |
#### to_dict(include_frames=False, include_private=False)
Serializes the sample view to a JSON dictionary.
* **Parameters:**
* **include_frames** (*False*) – whether to include the frame labels for
video samples
* **include_private** (*False*) – whether to include private fields
* **Returns:**
a JSON dict
#### save()
Saves the sample view to the database.
#### WARNING
This will permanently delete any omitted or filtered contents from
the source dataset.
#### add_labels(labels, label_field=None, confidence_thresh=None, classes=None, expand_schema=True, validate=True, dynamic=False)
Adds the given labels to the sample.
The provided `labels` can be any of the following:
- A [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) instance, in which case the
labels are directly saved in the specified `label_field`
- A dict mapping keys to [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label)
instances. In this case, the labels are added as follows:
```default
for key, value in labels.items():
sample[label_key(key)] = value
```
- A dict mapping frame numbers to [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label)
instances. In this case, the provided labels are interpreted as
frame-level labels that should be added as follows:
```default
sample.frames.merge(
{
frame_number: {label_field: label}
for frame_number, label in labels.items()
}
)
```
- A dict mapping frame numbers to dicts mapping keys to
[`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) instances. In this case, the
provided labels are interpreted as frame-level labels that should
be added as follows:
```default
sample.frames.merge(
{
frame_number: {
label_key(key): value
for key, value in frame_dict.items()
}
for frame_number, frame_dict in labels.items()
}
)
```
In the above, the `label_key` function maps label dict keys to field
names, and is defined from `label_field` as follows:
```default
if isinstance(label_field, dict):
label_key = lambda k: label_field.get(k, k)
elif label_field is not None:
label_key = lambda k: label_field + "_" + k
else:
label_key = lambda k: k
```
* **Parameters:**
* **labels** – a [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) or dict of labels per
the description above
* **label_field** (*None*) – the sample field, prefix, or dict defining in
which field(s) to save the labels
* **confidence_thresh** (*None*) – an optional confidence threshold to apply
to any applicable labels before saving them
* **classes** (*None*) – an optional iterable of classes to which to
restrict any applicable labels generated by the model
* **expand_schema** (*True*) – whether to dynamically add new fields
encountered to the dataset schema. If False, an error is raised
if any fields are not in the dataset schema
* **validate** (*True*) – whether to validate values for existing fields
* **dynamic** (*False*) – whether to declare dynamic attributes
#### clear_field(field_name)
Clears the value of a field of the document.
* **Parameters:**
**field_name** – the name of the field to clear
* **Raises:**
**AttributeError** – if the field does not exist
#### compute_metadata(overwrite=False, skip_failures=False)
Populates the `metadata` field of the sample.
* **Parameters:**
* **overwrite** (*False*) – whether to overwrite existing metadata
* **skip_failures** (*False*) – whether to gracefully continue without
raising an error if metadata cannot be computed
#### copy(fields=None, omit_fields=None)
Returns a deep copy of the sample that has not been added to the
database.
* **Parameters:**
* **fields** (*None*) – an optional field or iterable of fields to which to
restrict the copy. This can also be a dict mapping existing
field names to new field names
* **omit_fields** (*None*) – an optional field or iterable of fields to
exclude from the copy
* **Returns:**
a [`Sample`](#fiftyone.core.sample.Sample)
#### *property* dataset
The dataset to which this document belongs, or `None` if it has
not been added to a dataset.
#### *property* dataset_id
#### *property* excluded_field_names
The set of field names that are excluded on this document view, or
`None` if no fields are explicitly excluded.
#### *property* field_names
An ordered tuple of field names of this document view.
This may be a subset of all fields of the document if fields have been
selected or excluded.
#### *property* filename
The basename or logical display name of the sample’s media.
#### *property* filtered_field_names
The set of field names or `embedded.field.names` that have been
filtered on this document view, or `None` if no fields are filtered.
#### get_field(field_name)
Gets the value of a field of the document.
* **Parameters:**
**field_name** – the field name
* **Returns:**
the field value
* **Raises:**
**AttributeError** – if the field does not exist
#### get_media_key()
Returns the sample’s active logical media key.
Reference-backed samples return their reference’s key. All other
samples return their filepath.
#### has_field(field_name)
Determines whether the document has the given field.
* **Parameters:**
**field_name** – the field name
* **Returns:**
True/False
#### *property* in_dataset
Whether the document has been added to a dataset.
#### iter_fields(include_id=False, include_timestamps=False)
Returns an iterator over the `(name, value)` pairs of the public
fields of the document.
* **Parameters:**
* **include_id** (*False*) – whether to include the `id` field
* **include_timestamps** (*False*) – whether to include the `created_at`
and `last_modified_at` fields
* **Returns:**
an iterator that emits `(name, value)` tuples
#### *property* media_reference
The sample’s
[`fiftyone.core.media_reference.MediaReference`](fiftyone.core.media_reference.md#fiftyone.core.media_reference.MediaReference), or None for a filepath-backed sample.
The reference says which media source the sample’s media comes from
and where in it the sample is; the source itself is recorded once on
the dataset.
#### *property* media_type
The media type of the sample.
#### merge(sample, fields=None, omit_fields=None, merge_lists=True, merge_embedded_docs=False, overwrite=True, expand_schema=True, validate=True, dynamic=False)
Merges the fields of the given sample into this sample.
The behavior of this method is highly customizable. By default, all
top-level fields from the provided sample are merged in, overwriting
any existing values for those fields, with the exception of list fields
(e.g., `tags`) and label list fields (e.g.,
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) fields), in which case the
elements of the lists themselves are merged. In the case of label list
fields, labels with the same `id` in both samples are updated rather
than duplicated.
To avoid confusion between missing fields and fields whose value is
`None`, `None`-valued fields are always treated as missing while
merging.
This method can be configured in numerous ways, including:
- Whether new fields can be added to the dataset schema
- Whether list fields should be treated as ordinary fields and merged
as a whole rather than merging their elements
- Whether to merge only specific fields, or all but certain fields
- Mapping input sample fields to different field names of this sample
* **Parameters:**
* **sample** – a [`fiftyone.core.sample.Sample`](#fiftyone.core.sample.Sample)
* **fields** (*None*) – an optional field or iterable of fields to which to
restrict the merge. May contain frame fields for video samples.
This can also be a dict mapping field names of the input sample
to field names of this sample
* **omit_fields** (*None*) – an optional field or iterable of fields to
exclude from the merge. May contain frame fields for video
samples
* **merge_lists** (*True*) – whether to merge the elements of list fields
(e.g., `tags`) and label list fields (e.g.,
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) fields) rather than
merging the entire top-level field like other field types.
For label lists fields, existing
`fiftyone.core.label.Label` elements are either replaced
(when `overwrite` is True) or kept (when `overwrite` is
False) when their `id` matches a label from the provided
sample
* **merge_embedded_docs** (*False*) – whether to merge the attributes of
embedded documents (True) rather than merging the entire
top-level field (False)
* **overwrite** (*True*) – whether to overwrite (True) or skip (False)
existing fields and label elements
* **expand_schema** (*True*) – whether to dynamically add new fields
encountered to the dataset schema. If False, an error is raised
if any fields are not in the dataset schema
* **validate** (*True*) – whether to validate values for existing fields
* **dynamic** (*False*) – whether to declare dynamic embedded document
fields
#### *property* selected_field_names
The set of field names that are selected on this document view, or
`None` if no fields are explicitly selected.
#### set_field(field_name, value, create=True, validate=True, dynamic=False)
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
* **validate** (*True*) – whether to validate values for existing fields
* **dynamic** (*False*) – whether to declare dynamic embedded document
fields
* **Raises:**
* **ValueError** – if `field_name` is not an allowed field name
* **AttributeError** – if the field does not exist and `create == False`
#### to_json(pretty_print=False)
Serializes the document to a JSON string.
The document ID and private fields are excluded in this representation.
* **Parameters:**
**pretty_print** (*False*) – whether to render the JSON in human readable
format with newlines and indentations
* **Returns:**
a JSON string
#### to_mongo_dict(include_id=False)
Serializes the document to a BSON dictionary equivalent to the
representation that would be stored in the database.
* **Parameters:**
**include_id** (*False*) – whether to include the document ID
* **Returns:**
a BSON dict
#### update_fields(fields_dict, expand_schema=True, validate=True, dynamic=False)
Sets the dictionary of fields on the document.
* **Parameters:**
* **fields_dict** – a dict mapping field names to values
* **expand_schema** (*True*) – whether to dynamically add new fields
encountered to the document schema. If False, an error is
raised if any fields are not in the document schema
* **validate** (*True*) – whether to validate values for existing fields
* **dynamic** (*False*) – whether to declare dynamic embedded document
fields
* **Raises:**
**AttributeError** – if `expand_schema == False` and a field does not
exist