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.
voxel51.com

Functions:

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