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

# fiftyone.core.groups

Sample groups.

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

**Classes:**

| [`Group`](#fiftyone.core.groups.Group)(\*args, \*\*kwargs)   | A named group membership.   |
|--------------------------------------------------------------|-----------------------------|

**Functions:**

| [`get_group_slice_name`](#fiftyone.core.groups.get_group_slice_name)(sample, group_field)   | Gets the group slice name for a sample, if available.   |
|---------------------------------------------------------------------------------------------|---------------------------------------------------------|
| [`is_group_field`](#fiftyone.core.groups.is_group_field)(field)                             | Determines whether the given field is a group field.    |

### *class* fiftyone.core.groups.Group(\*args, \*\*kwargs)

Bases: [`EmbeddedDocument`](fiftyone.core.odm.embedded_document.md#fiftyone.core.odm.embedded_document.EmbeddedDocument)

A named group membership.

* **Parameters:**
  * **id** (*None*) – the group ID
  * **name** (*None*) – the group name

**Attributes:**

| [`id`](#fiftyone.core.groups.Group.id)                   | An Object ID field.                                     |
|----------------------------------------------------------|---------------------------------------------------------|
| [`name`](#fiftyone.core.groups.Group.name)               | A unicode string field.                                 |
| [`STRICT`](#fiftyone.core.groups.Group.STRICT)           |                                                         |
| [`field_names`](#fiftyone.core.groups.Group.field_names) | An ordered tuple of the public fields of this document. |

**Methods:**

| [`element`](#fiftyone.core.groups.Group.element)(name)                                   |                                                                                                          |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------|
| [`clean`](#fiftyone.core.groups.Group.clean)()                                           | Hook for doing document level data cleaning (usually validation or assignment) before validation is run. |
| [`clear_field`](#fiftyone.core.groups.Group.clear_field)(field_name)                     | Clears the field from the document.                                                                      |
| [`copy`](#fiftyone.core.groups.Group.copy)()                                             | Returns a deep copy of the document.                                                                     |
| [`fancy_repr`](#fiftyone.core.groups.Group.fancy_repr)([class_name, select_fields, ...]) | Generates a customizable string representation of the document.                                          |
| [`field_to_mongo`](#fiftyone.core.groups.Group.field_to_mongo)(field_name)               |                                                                                                          |
| [`field_to_python`](#fiftyone.core.groups.Group.field_to_python)(field_name, value)      |                                                                                                          |
| [`from_dict`](#fiftyone.core.groups.Group.from_dict)(d[, extended])                      | Loads the document from a BSON/JSON dictionary.                                                          |
| [`from_json`](#fiftyone.core.groups.Group.from_json)(s)                                  | Loads the document from a JSON string.                                                                   |
| [`get_field`](#fiftyone.core.groups.Group.get_field)(field_name)                         | Gets the field of the document.                                                                          |
| [`get_text_score`](#fiftyone.core.groups.Group.get_text_score)()                         | Get text score from text query                                                                           |
| [`has_field`](#fiftyone.core.groups.Group.has_field)(field_name)                         | Determines whether the document has a field of the given name.                                           |
| [`iter_fields`](#fiftyone.core.groups.Group.iter_fields)()                               | Returns an iterator over the `(name, value)` pairs of the public fields of the document.                 |
| [`merge`](#fiftyone.core.groups.Group.merge)(doc[, merge_lists, merge_dicts, overwrite]) | Merges the contents of the given document into this document.                                            |
| [`set_field`](#fiftyone.core.groups.Group.set_field)(field_name, value[, create])        | Sets the value of a field of the document.                                                               |
| [`to_dict`](#fiftyone.core.groups.Group.to_dict)([extended])                             | Serializes this document to a BSON/JSON dictionary.                                                      |
| [`to_json`](#fiftyone.core.groups.Group.to_json)([pretty_print])                         | Serializes the document to a JSON string.                                                                |
| [`to_mongo`](#fiftyone.core.groups.Group.to_mongo)(\*args, \*\*kwargs)                   | Return as SON data ready for use with MongoDB.                                                           |
| [`validate`](#fiftyone.core.groups.Group.validate)([clean])                              | Ensure that all fields' values are valid and that required fields are present.                           |

**Classes:**

| [`my_metaclass`](#fiftyone.core.groups.Group.my_metaclass)   |    |
|--------------------------------------------------------------|----|

#### id

An Object ID field.

* **Parameters:**
  * **description** (*None*) – an optional description
  * **info** (*None*) – an optional info dict
  * **read_only** (*False*) – whether the field is read-only
  * **created_at** (*None*) – the datetime the field was created

#### name

A unicode string field.

* **Parameters:**
  * **description** (*None*) – an optional description
  * **info** (*None*) – an optional info dict
  * **read_only** (*False*) – whether the field is read-only
  * **created_at** (*None*) – the datetime the field was created

#### element(name)

#### STRICT *= False*

#### clean()

Hook for doing document level data cleaning (usually validation or assignment)
before validation is run.

Any ValidationError raised by this method will not be associated with
a particular field; it will have a special-case association with the
field defined by NON_FIELD_ERRORS.

#### clear_field(field_name)

Clears the field from the document.

* **Parameters:**
  **field_name** – the field name
* **Raises:**
  **ValueError** – if the field does not exist

#### copy()

Returns a deep copy of the document.

* **Returns:**
  a `SerializableDocument`

#### fancy_repr(class_name=None, select_fields=None, exclude_fields=None, \*\*kwargs)

Generates a customizable string representation of the document.

* **Parameters:**
  * **class_name** (*None*) – optional class name to use
  * **select_fields** (*None*) – iterable of field names to restrict to
  * **exclude_fields** (*None*) – iterable of field names to exclude
  * **\*\*kwargs** – additional key-value pairs to include in the string
    representation
* **Returns:**
  a string representation of the document

#### *property* field_names

An ordered tuple of the public fields of this document.

#### field_to_mongo(field_name)

#### field_to_python(field_name, value)

#### *classmethod* from_dict(d, extended=False)

Loads the document from a BSON/JSON dictionary.

* **Parameters:**
  * **d** – a dictionary
  * **extended** (*False*) – whether the input dictionary may contain
    serialized extended JSON constructs
* **Returns:**
  a `SerializableDocument`

#### *classmethod* from_json(s)

Loads the document from a JSON string.

* **Returns:**
  a `SerializableDocument`

#### get_field(field_name)

Gets the field of the document.

* **Parameters:**
  **field_name** – the field name
* **Returns:**
  the field value
* **Raises:**
  **AttributeError** – if the field does not exist

#### get_text_score()

Get text score from text query

#### has_field(field_name)

Determines whether the document has a field of the given name.

* **Parameters:**
  **field_name** – the field name
* **Returns:**
  True/False

#### iter_fields()

Returns an iterator over the `(name, value)` pairs of the
public fields of the document.

* **Returns:**
  an iterator that emits `(name, value)` tuples

#### merge(doc, merge_lists=True, merge_dicts=True, overwrite=True)

Merges the contents of the given document into this document.

* **Parameters:**
  * **doc** – a `SerializableDocument` of same type as this document
  * **merge_lists** (*True*) – whether to merge the elements of top-level list
    fields rather than treating the list as a single value
  * **merge_dicts** (*True*) – whether to recursively merge the contents of
    top-level dict fields rather than treating the dict as a single
    value
  * **overwrite** (*True*) – whether to overwrite (True) or skip (False)
    existing fields

#### my_metaclass

alias of `DocumentMetaclass`

#### set_field(field_name, value, create=True)

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
* **Raises:**
  **ValueError** – if `field_name` is not an allowed field name or does
      not exist and `create == False`

#### to_dict(extended=False)

Serializes this document to a BSON/JSON dictionary.

* **Parameters:**
  **extended** (*False*) – whether to serialize extended JSON constructs
  such as ObjectIDs, Binary, etc. into JSON format
* **Returns:**
  a dict

#### to_json(pretty_print=False)

Serializes the document to a JSON string.

* **Parameters:**
  **pretty_print** (*False*) – whether to render the JSON in human readable
  format with newlines and indentations
* **Returns:**
  a JSON string

#### to_mongo(\*args, \*\*kwargs)

Return as SON data ready for use with MongoDB.

#### validate(clean=True)

Ensure that all fields’ values are valid and that required fields
are present.

Raises `ValidationError` if any of the fields’ values are found
to be invalid.

### fiftyone.core.groups.get_group_slice_name(sample, group_field)

Gets the group slice name for a sample, if available.

* **Parameters:**
  * **sample** – a [`fiftyone.core.sample.Sample`](fiftyone.core.sample.md#fiftyone.core.sample.Sample)
  * **group_field** – the dataset’s group field name
* **Returns:**
  the slice name, or `None`

### fiftyone.core.groups.is_group_field(field)

Determines whether the given field is a group field.

* **Parameters:**
  **field** – a [`fiftyone.core.fields.Field`](fiftyone.core.fields.md#fiftyone.core.fields.Field)
* **Returns:**
  True/False