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

# fiftyone.core.subsets

Saved episode and segment subsets.

Membership is frozen, while samples and annotations remain live. Removing a
sample retains its saved references. Subsets are scoped to their owning dataset;
clones and snapshots do not inherit them. Converted subsets retain their source
identities independently of generated collections. Anonymous clip bounds are
frozen; annotation clips stay live.

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

**Functions:**

| [`create_subset`](#fiftyone.core.subsets.create_subset)(dataset, name[, description, ...])          | Creates a named subset without copying any media or annotations.         |
|-----------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------|
| [`save_subset`](#fiftyone.core.subsets.save_subset)(dataset, name[, samples, ...])                  | Captures SDK samples or explicit members in a new saved subset.          |
| [`add_members`](#fiftyone.core.subsets.add_members)(dataset, subset_id[, samples, ...])             | Adds SDK samples or explicit references using the shared retry journal.  |
| [`capture_source`](#fiftyone.core.subsets.capture_source)(dataset[, stages, saved_view])            | Describes where a capture's members came from.                           |
| [`has_subsets`](#fiftyone.core.subsets.has_subsets)(dataset)                                        | Checks whether the dataset owns any subsets without loading metadata.    |
| [`has_subset`](#fiftyone.core.subsets.has_subset)(dataset, subset_id)                               | Checks one dataset-scoped ID without resolving names or members.         |
| [`list_subsets`](#fiftyone.core.subsets.list_subsets)(dataset[, info, name])                        | Lists dataset-scoped metadata or IDs, optionally matching an exact name. |
| [`browse_subsets`](#fiftyone.core.subsets.browse_subsets)(dataset[, search, skip, ...])             | Pages the current dataset's subsets, optionally matching a search.       |
| [`async_browse_subsets`](#fiftyone.core.subsets.async_browse_subsets)(dataset[, search, ...])       | Pages saved subset metadata asynchronously, without live recounts.       |
| [`subset_summary`](#fiftyone.core.subsets.subset_summary)(dataset, subset_id[, counts])             | One subset's saved counts, optionally resolving live availability.       |
| [`update_subset_info`](#fiftyone.core.subsets.update_subset_info)(dataset, subset_id, info)         | Updates a subset's name/description without changing its attribution.    |
| [`async_subset_summary`](#fiftyone.core.subsets.async_subset_summary)(dataset, subset_id)           | Reads saved metadata in one async lookup, without resolving members.     |
| [`get_subset`](#fiftyone.core.subsets.get_subset)(dataset, subset_id[, captures])                   | Returns a dataset-scoped subset or raises rather than broadening scope.  |
| [`member_count`](#fiftyone.core.subsets.member_count)(dataset, subset_id)                           | Reads the saved entity count with one subset document lookup.            |
| [`split_subset_view`](#fiftyone.core.subsets.split_subset_view)(stages)                             | Separates an entity conversion from stages applied within its subset.    |
| [`subset_view_key`](#fiftyone.core.subsets.subset_view_key)(stages, dataset)                        | Identifies compatible entities independently of materialization.         |
| [`subset_base_view`](#fiftyone.core.subsets.subset_base_view)(dataset, subset_id[, stages])         | Loads the subset's element domain and keeps later filters separate.      |
| [`load_materialized_view`](#fiftyone.core.subsets.load_materialized_view)(source, subset_id, stage) | Shares one generated frame/range view for a subset membership version.   |
| [`write_clips_dataset`](#fiftyone.core.subsets.write_clips_dataset)(dataset, subset_id, ...)        | Materializes saved anonymous clips using exact inclusive supports.       |
| [`write_frames_dataset`](#fiftyone.core.subsets.write_frames_dataset)(dataset, subset_id, ...)      | Materializes only saved positions, including frames without native docs. |
| [`delete_subset`](#fiftyone.core.subsets.delete_subset)(dataset, subset_id)                         | Deletes a subset and its frozen records; media and annotations stay.     |
| [`subset_members`](#fiftyone.core.subsets.subset_members)(dataset, subset_id[, scope])              | Reads frozen membership; deleted parent references remain stored.        |
| [`remove_members`](#fiftyone.core.subsets.remove_members)(dataset, subset_id, members)              | Removes exact member references from a subset, leaving samples intact.   |
| [`prepare_add`](#fiftyone.core.subsets.prepare_add)(dataset, subset_id, ...[, ...])                 | Freezes a validated add and previews changes in bounded batches.         |
| [`is_add_prepared`](#fiftyone.core.subsets.is_add_prepared)(dataset, subset_id, operation_id)       | Whether a retry can reuse stored candidates after its snapshot expires.  |
| [`apply_add`](#fiftyone.core.subsets.apply_add)(dataset, operation_id[, progress])                  | Applies frozen candidates with idempotent, bounded bulk writes.          |
| [`validate_members`](#fiftyone.core.subsets.validate_members)(dataset, members[, subset_id])        | Accepts source parents and exact saved references to deleted parents.    |
| [`delete_for_dataset_id`](#fiftyone.core.subsets.delete_for_dataset_id)(dataset_id)                 | Deletes subset records only when the owning dataset itself is deleted.   |
| [`member_query`](#fiftyone.core.subsets.member_query)(dataset, subset_id[, scope])                  | Resolves a dataset-scoped, unambiguous subset membership query.          |
| [`select_subset`](#fiftyone.core.subsets.select_subset)(view, subset_id[, scope, ...])              | Starts at saved membership so sparse subsets do not scan every sample.   |
| [`iter_parent_members`](#fiftyone.core.subsets.iter_parent_members)(dataset, subset_id, ...)        | Streams exact saved references for a bounded set of requested parents.   |
| [`iter_view_members`](#fiftyone.core.subsets.iter_view_members)(view, subset_id[, scope])           | Streams membership in view order without enumerating parents in Python.  |
| [`iter_missing_members`](#fiftyone.core.subsets.iter_missing_members)(dataset, subset_id[, scope])  | Streams saved references whose parents have been deleted.                |
| [`collection_counts`](#fiftyone.core.subsets.collection_counts)(dataset, name, query[, target])     | Computes live membership counts in Mongo with bounded client memory.     |
| [`subset_counts`](#fiftyone.core.subsets.subset_counts)(dataset, subset_id[, scope])                | Counts saved members, including missing parents, without loading them.   |
| [`view_counts`](#fiftyone.core.subsets.view_counts)(view, subset_id[, scope])                       | Counts only saved members whose live parents match the current view.     |
| [`missing_counts`](#fiftyone.core.subsets.missing_counts)(dataset, subset_id[, scope])              | Counts missing parents and each saved member kind entirely in Mongo.     |
| [`missing_member_page`](#fiftyone.core.subsets.missing_member_page)(dataset, subset_id[, ...])      | Returns one page of unavailable parents, with their complete ranges.     |

### fiftyone.core.subsets.create_subset(dataset, name, description=None, view=None, preferred_group_slice=None, provenance=None, lineage=None)

Creates a named subset without copying any media or annotations.

`provenance` and `lineage` are optional JSON dictionaries describing
how this subset was produced and its upstream inputs. Each may contain at
most 64 KiB of BSON. They are descriptive metadata, not live references;
deleting an upstream subset does not change them or this subset’s members.

### fiftyone.core.subsets.save_subset(dataset, name, samples=None, description=None, members=None, provenance=None, lineage=None, view=None)

Captures SDK samples or explicit members in a new saved subset.

### fiftyone.core.subsets.add_members(dataset, subset_id, samples=None, members=None, operation_id=None, source=None)

Adds SDK samples or explicit references using the shared retry journal.

A sample collection records itself as the capture’s source; `source`
describes explicit members, as built by [`capture_source()`](#fiftyone.core.subsets.capture_source).

### fiftyone.core.subsets.capture_source(dataset, stages=None, saved_view=None)

Describes where a capture’s members came from.

`stages` are the serialized view stages the capture ran against, and
`saved_view` names the saved view that was loaded, if any. The saved
view is recorded by ID, name, and slug as of the capture, so the record
keeps its meaning after the saved view is renamed or deleted. Stages over
16 KiB of BSON, such as long ID lists, are left out.

* **Parameters:**
  * **dataset** – the subset’s [`fiftyone.core.dataset.Dataset`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset)
  * **stages** (*None*) – a list of serialized view stages
  * **saved_view** (*None*) – the name of a saved view on `dataset`
* **Returns:**
  a source dict, or None when there is nothing to record

### fiftyone.core.subsets.has_subsets(dataset)

Checks whether the dataset owns any subsets without loading metadata.

### fiftyone.core.subsets.has_subset(dataset, subset_id)

Checks one dataset-scoped ID without resolving names or members.

### fiftyone.core.subsets.list_subsets(dataset, info=True, name=None)

Lists dataset-scoped metadata or IDs, optionally matching an exact name.

Internal callers receive metadata by default. The public Dataset API
defaults to IDs and passes its `info` preference explicitly.

### fiftyone.core.subsets.browse_subsets(dataset, search=None, skip=0, limit=None, counts=False, view=None, metadata=False)

Pages the current dataset’s subsets, optionally matching a search.

Names and descriptions match case-insensitively. The result carries the
page, how many subsets match, and how many the dataset has in all, so a
picker knows whether search is worth offering. Supplying `view` limits
results to compatible subsets; an empty view selects sample subsets.
Omitting it lists every subset in the dataset.
Set `metadata=True` to include optional provenance and lineage.

### *async* fiftyone.core.subsets.async_browse_subsets(dataset, search=None, skip=0, limit=None, view=None, metadata=False)

Pages saved subset metadata asynchronously, without live recounts.

### fiftyone.core.subsets.subset_summary(dataset, subset_id, counts=False)

One subset’s saved counts, optionally resolving live availability.

### fiftyone.core.subsets.update_subset_info(dataset, subset_id, info)

Updates a subset’s name/description without changing its attribution.

### *async* fiftyone.core.subsets.async_subset_summary(dataset, subset_id)

Reads saved metadata in one async lookup, without resolving members.

### fiftyone.core.subsets.get_subset(dataset, subset_id, captures=False)

Returns a dataset-scoped subset or raises rather than broadening scope.

The capture history is only read when `captures` is True.

### fiftyone.core.subsets.member_count(dataset, subset_id)

Reads the saved entity count with one subset document lookup.

Each whole entity or segment counts once, including unavailable references.
This does not resolve parents or apply view filters.

### fiftyone.core.subsets.split_subset_view(stages)

Separates an entity conversion from stages applied within its subset.

### fiftyone.core.subsets.subset_view_key(stages, dataset)

Identifies compatible entities independently of materialization.

### fiftyone.core.subsets.subset_base_view(dataset, subset_id, stages=None)

Loads the subset’s element domain and keeps later filters separate.

### fiftyone.core.subsets.load_materialized_view(source, subset_id, stage, reload=False)

Shares one generated frame/range view for a subset membership version.

Grid and modal requests must resolve to the same frame IDs. Publishing the
cache with a compare-and-set lets concurrent requests share a winner on
standalone Mongo, without holding a lock while generating a collection.

### fiftyone.core.subsets.write_clips_dataset(dataset, subset_id, clips_dataset)

Materializes saved anonymous clips using exact inclusive supports.

The join starts at saved membership and streams through Mongo, so neither
the view definition nor Python memory grows with the number of clips.

### fiftyone.core.subsets.write_frames_dataset(dataset, subset_id, frames_dataset)

Materializes only saved positions, including frames without native docs.

### fiftyone.core.subsets.delete_subset(dataset, subset_id)

Deletes a subset and its frozen records; media and annotations stay.

### fiftyone.core.subsets.subset_members(dataset, subset_id, scope=None)

Reads frozen membership; deleted parent references remain stored.

### fiftyone.core.subsets.remove_members(dataset, subset_id, members, counts=True)

Removes exact member references from a subset, leaving samples intact.

Whole episodes and segments have separate identities. Removing an episode
does not remove its saved segments, and provenance does not affect which
segment is removed. Repeating a removal leaves absent members unchanged.

* **Parameters:**
  * **dataset** – the owning [`fiftyone.core.dataset.Dataset`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset)
  * **subset_id** – the subset ID
  * **members** – the episode and segment references to remove
* **Returns:**
  a dict with the subset ID, removed count, and remaining member counts

### fiftyone.core.subsets.prepare_add(dataset, subset_id, operation_id, members, snapshot=None, progress=None, preview=True, source=None)

Freezes a validated add and previews changes in bounded batches.

`snapshot` is server-owned metadata for a normalized member iterator.
`source`, from [`capture_source()`](#fiftyone.core.subsets.capture_source), is recorded in the subset’s
captures once the add applies.
Explicit members are validated against source samples or existing saved
identities, so a deleted parent can be carried forward without admitting
arbitrary foreign or generated IDs. Retry receipts expire after seven days.

### fiftyone.core.subsets.is_add_prepared(dataset, subset_id, operation_id, members=None, snapshot_id=None)

Whether a retry can reuse stored candidates after its snapshot expires.

### fiftyone.core.subsets.apply_add(dataset, operation_id, progress=None)

Applies frozen candidates with idempotent, bounded bulk writes.

Membership and provenance retain their first adding operation. A concurrent
removal is allowed to win; it must not turn receipt counting into an error.
Completed operations keep their result but release their candidate payload.

### fiftyone.core.subsets.validate_members(dataset, members, subset_id=None)

Accepts source parents and exact saved references to deleted parents.

### fiftyone.core.subsets.delete_for_dataset_id(dataset_id)

Deletes subset records only when the owning dataset itself is deleted.

### fiftyone.core.subsets.member_query(dataset, subset_id, scope=None)

Resolves a dataset-scoped, unambiguous subset membership query.

### fiftyone.core.subsets.select_subset(view, subset_id, scope=None, parent_ids=None)

Starts at saved membership so sparse subsets do not scan every sample.

Grouped or already-filtered views keep their input slice/stage semantics via
an existence join. A base non-grouped view can start from the subset index
and fetch only its live parents. Later stages still see normal sample docs.

### fiftyone.core.subsets.iter_parent_members(dataset, subset_id, scope, parent_ids)

Streams exact saved references for a bounded set of requested parents.

### fiftyone.core.subsets.iter_view_members(view, subset_id, scope=None)

Streams membership in view order without enumerating parents in Python.

### fiftyone.core.subsets.iter_missing_members(dataset, subset_id, scope=None)

Streams saved references whose parents have been deleted.

### fiftyone.core.subsets.collection_counts(dataset, name, query, target=None)

Computes live membership counts in Mongo with bounded client memory.

### fiftyone.core.subsets.subset_counts(dataset, subset_id, scope=None)

Counts saved members, including missing parents, without loading them.

### fiftyone.core.subsets.view_counts(view, subset_id, scope=None)

Counts only saved members whose live parents match the current view.

### fiftyone.core.subsets.missing_counts(dataset, subset_id, scope=None)

Counts missing parents and each saved member kind entirely in Mongo.

### fiftyone.core.subsets.missing_member_page(dataset, subset_id, scope=None, skip=0, limit=100)

Returns one page of unavailable parents, with their complete ranges.