fiftyone.operators.store

• fiftyone.operators.store.models
• fiftyone.operators.store.service
• fiftyone.operators.store.store

Module contents

Execution store.

Copyright 2017-2025, Voxel51, Inc.

voxel51.com

Classes:

ExecutionStoreService(repo, dataset_id, …)	Service for managing execution store operations.
ExecutionStore(store_name, store_service, …)	Execution store.
StoreDocument(store_name, key, value, _id, …)	Model representing a Store.
KeyDocument(store_name, key, value, _id, …)	Model representing a key in the store.
KeyPolicy(value)	Defines the eviction policy for a key in the execution store.

class fiftyone.operators.store.ExecutionStoreService(repo: Optional[ExecutionStoreRepo] = None, dataset_id: Optional[bson.objectid.ObjectId] = None, collection_name: str = None)

Bases: object

Service for managing execution store operations.

Note that each instance of this service has a context:

• If a dataset_id is provided (or a repo associated with one), this instance operates on stores associated with that dataset

• If no dataset_id is provided (or a repo is provided that is not associated with one), this instance operates on stores that are not associated with a dataset

To operate on all stores across all contexts, use the XXX_global() methods that this class provides.

Parameters

• repo (None) – a fiftyone.factory.repos.execution_store.ExecutionStoreRepo If not provided, a new fiftyone.factory.repos.execution_store.MongoExecutionStoreRepo will be created

• dataset_id (None) – a dataset ID to scope operations to

• collection_name (None) – a collection name to use for the execution store. If repo is provided, this argument is ignored

Methods:

create_store(store_name[, metadata, policy])	Creates a new store with the specified name.
clear_cache([store_name])	Clears all cache entries in the execution stores.
get_store(store_name)	Gets the specified store for the current context.
list_stores()	Lists all stores for the current context.
count_stores()	Counts the stores for the current context.
has_store(store_name)	Determines whether the specified store exists in the current context.
delete_store(store_name)	Deletes the specified store.
set_key(store_name, key, value[, ttl, policy])	Sets the value of a key in the specified store.
set_cache_key(store_name, key, value[, ttl])	Sets the value of a cache key in the specified store.
has_key(store_name, key)	Determines whether the specified key exists in the specified store.
get_key(store_name, key)	Retrieves the value of a key from the specified store.
delete_key(store_name, key)	Deletes the specified key from the store.
update_ttl(store_name, key, new_ttl)	Updates the TTL of the specified key in the store.
list_keys(store_name)	Lists all keys in the specified store.
count_keys(store_name)	Counts the keys in the specified store.
cleanup()	Deletes all stores associated with the current context.
has_store_global(store_name)	Determines whether a store with the given name exists across all datasets and the global context.
list_stores_global()	Lists the stores across all datasets and the global context.
count_stores_global()	Counts the stores across all datasets and the global context.
delete_store_global(store_name)	Deletes the specified store across all datasets and the global context.

create_store(store_name: str, metadata: Optional[dict] = None, policy: str = 'persist') → fiftyone.operators.store.models.StoreDocument

Creates a new store with the specified name.

Parameters

store_name – the name of the store

Returns

a fiftyone.store.models.StoreDocument

clear_cache(store_name=None) → None

Clears all cache entries in the execution stores.

get_store(store_name: str) → fiftyone.operators.store.models.StoreDocument

Gets the specified store for the current context.

Parameters

store_name – the name of the store

Returns

a fiftyone.store.models.StoreDocument

list_stores() → list

Lists all stores for the current context.

Returns

a list of store names

count_stores() → int

Counts the stores for the current context.

Returns

the number of stores

has_store(store_name) → bool

Determines whether the specified store exists in the current context.

Parameters

store_name – the name of the store

Returns

True/False

delete_store(store_name: str) → fiftyone.operators.store.models.StoreDocument

Deletes the specified store.

Parameters

store_name – the name of the store

Returns

a fiftyone.store.models.StoreDocument

set_key(store_name: str, key: str, value: Any, ttl: Optional[int] = None, policy: str = 'persist') → fiftyone.operators.store.models.KeyDocument

Sets the value of a key in the specified store.

Keys can be either persistent or cacheable, depending on the provided policy or whether a TTL (time-to-live) is set.

• If policy="persist" (default), the key will remain in the store until explicitly deleted.

• If policy="evict", the key may be evicted by the system or manually removed using clear_cache().

• If a TTL is provided, the key is always treated as policy="evict".

Parameters

• store_name – the name of the store

• key – the key to set

• value – the value to set

• ttl (None) – an optional TTL in seconds

• policy (persist) – the eviction policy for the key. Can be “persist” or “evict”. If “persist”, the key will never be automatically removed. If “evict”, the key may be removed automatically if a TTL is set, or manually via clear_cache().

Returns

The created or updated key document.

Return type

KeyDocument

set_cache_key(store_name: str, key: str, value: Any, ttl: Optional[int] = None) → fiftyone.operators.store.models.KeyDocument

Sets the value of a cache key in the specified store.

Parameters

• store_name – the name of the store

• key – the key to set

• value – the value to set

• ttl (None) – an optional TTL in seconds

has_key(store_name: str, key: str) → bool

Determines whether the specified key exists in the specified store.

Parameters

• store_name – the name of the store

• key – the key to check

get_key(store_name: str, key: str) → fiftyone.operators.store.models.KeyDocument

Retrieves the value of a key from the specified store.

Parameters

• store_name – the name of the store

• key – the key to retrieve

Returns

a fiftyone.store.models.KeyDocument

delete_key(store_name: str, key: str) → bool

Deletes the specified key from the store.

Parameters

• store_name – the name of the store

• key – the key to delete

Returns

True if the key was deleted, False otherwise

update_ttl(store_name: str, key: str, new_ttl: int) → fiftyone.operators.store.models.KeyDocument

Updates the TTL of the specified key in the store.

Parameters

• store_name – the name of the store

• key – the key to update the TTL for

• new_ttl – the new TTL in seconds

Returns

a fiftyone.store.models.KeyDocument

list_keys(store_name: str) → list

Lists all keys in the specified store.

Parameters

store_name – the name of the store

Returns

a list of keys in the store

count_keys(store_name: str) → int

Counts the keys in the specified store.

Parameters

store_name – the name of the store

Returns

the number of keys in the store

cleanup() → None

Deletes all stores associated with the current context.

has_store_global(store_name) → bool

Determines whether a store with the given name exists across all datasets and the global context.

Parameters

store_name – the name of the store

Returns

True/False

list_stores_global() → list

Lists the stores across all datasets and the global context.

Returns

a list of fiftyone.store.models.StoreDocument

count_stores_global() → int

Counts the stores across all datasets and the global context.

Returns

the number of stores

delete_store_global(store_name) → int

Deletes the specified store across all datasets and the global context.

Parameters

store_name – the name of the store

Returns

the number of stores deleted

class fiftyone.operators.store.ExecutionStore(store_name: str, store_service: fiftyone.operators.store.service.ExecutionStoreService, default_policy: str = 'persist')

Bases: object

Execution store.

Parameters

• store_name – the name of the store

• store_service – an fiftyone.operators.store.service.ExecutionStoreService

• default_policy ("persist") – the default eviction policy for the store.

Methods:

create(store_name[, dataset_id, …])
list_stores()	Lists all stores in the execution store.
get(key)	Retrieves a value from the store by its key.
set(key, value[, ttl, policy])	Sets the value of a key in the specified store.
set_cache(key, value[, ttl])	Sets a value in the store with the eviction policy set to “evict”.
delete(key)	Deletes a key from the store.
has(key)	Checks if the store has a specific key.
clear()	Clears all the data in the store.
clear_cache()	Clears the cache for the store.
update_ttl(key, new_ttl)	Updates the TTL for a specific key.
update_policy(key, policy)	Updates the eviction policy for a specific key.
get_metadata(key)	Retrieves the metadata for the given key.
list_keys()	Lists all keys in the store.

static create(store_name: str, dataset_id: Optional[bson.objectid.ObjectId] = None, default_policy: str = 'persist', collection_name: Optional[str] = None) → fiftyone.operators.store.store.ExecutionStore

list_stores() → list

Lists all stores in the execution store.

Returns

a list of store names

Return type

list

get(key: str) → Optional[Any]

Retrieves a value from the store by its key.

Parameters

key – the key to retrieve the value for

Returns

the value stored under the given key, or None if not found

set(key: str, value: Any, ttl: Optional[int] = None, policy=None) → None

Sets the value of a key in the specified store.

Parameters

• key – the key to set

• value – the value to set

• ttl (None) – an optional TTL in seconds

• policy (persist) – the eviction policy for the key. Can be “persist” or “evict”. If “persist”, the key will never be automatically removed. If “evict”, the key may be removed automatically if a TTL is set, or manually via clear_cache().

Returns

a fiftyone.store.models.KeyDocument

set_cache(key: str, value: Any, ttl: Optional[int] = None) → None

Sets a value in the store with the eviction policy set to “evict”.

Parameters

• key – the key to store the value under

• value – the value to store

• ttl (None) – the time-to-live in seconds

delete(key: str) → bool

Deletes a key from the store.

Parameters

key – the key to delete.

Returns

True/False whether the key was deleted

has(key: str) → bool

Checks if the store has a specific key.

Parameters

key – the key to check

Returns

True/False whether the key exists

clear() → None

Clears all the data in the store.

clear_cache() → None

Clears the cache for the store.

This will remove all keys that are eligible for eviction.

update_ttl(key: str, new_ttl: int) → None

Updates the TTL for a specific key.

Parameters

• key – the key to update the TTL for

• new_ttl – the new TTL in seconds

update_policy(key: str, policy: str) → None

Updates the eviction policy for a specific key.

Parameters

• key – the key to update the policy for

• policy – the new policy, either “persist” or “evict”

get_metadata(key: str) → Optional[dict]

Retrieves the metadata for the given key.

Parameters

key – the key to check

Returns

a dict of metadata about the key

list_keys() → list

Lists all keys in the store.

Returns

a list of keys in the store

class fiftyone.operators.store.StoreDocument(store_name: str, key: str = '__store__', value: Optional[dict] = None, _id: Optional[Any] = None, dataset_id: Optional[bson.objectid.ObjectId] = None, created_at: datetime.datetime = <factory>, updated_at: Optional[datetime.datetime] = None, expires_at: Optional[datetime.datetime] = None, policy: fiftyone.operators.store.models.KeyPolicy = <KeyPolicy.PERSIST: 'persist'>)

Bases: fiftyone.operators.store.models.KeyDocument

Model representing a Store.

Attributes:

key
value
metadata	The metadata associated with the store.
dataset_id
expires_at
policy
updated_at

Methods:

from_dict(doc)	Creates a KeyDocument from a dictionary.
get_expiration(ttl)	Gets the expiration date for a key with the given TTL.
to_mongo_dict([exclude_id])	Serializes the document to a MongoDB dictionary.

key: str = '__store__'

value: Optional[dict] = None

property metadata

The metadata associated with the store.

dataset_id: Optional[bson.objectid.ObjectId] = None

expires_at: Optional[datetime.datetime] = None

classmethod from_dict(doc: dict) → fiftyone.operators.store.models.KeyDocument

Creates a KeyDocument from a dictionary.

static get_expiration(ttl: Optional[int]) → Optional[datetime.datetime]

Gets the expiration date for a key with the given TTL.

policy: fiftyone.operators.store.models.KeyPolicy = 'persist'

to_mongo_dict(exclude_id: bool = True) → dict

Serializes the document to a MongoDB dictionary.

updated_at: Optional[datetime.datetime] = None

store_name: str

created_at: datetime.datetime

class fiftyone.operators.store.KeyDocument(store_name: str, key: str, value: Any, _id: Optional[Any] = None, dataset_id: Optional[bson.objectid.ObjectId] = None, created_at: datetime.datetime = <factory>, updated_at: Optional[datetime.datetime] = None, expires_at: Optional[datetime.datetime] = None, policy: fiftyone.operators.store.models.KeyPolicy = <KeyPolicy.PERSIST: 'persist'>)

Bases: object

Model representing a key in the store.

Attributes:

dataset_id
updated_at
expires_at
policy

Methods:

get_expiration(ttl)	Gets the expiration date for a key with the given TTL.
from_dict(doc)	Creates a KeyDocument from a dictionary.
to_mongo_dict([exclude_id])	Serializes the document to a MongoDB dictionary.

store_name: str

key: str

value: Any

dataset_id: Optional[bson.objectid.ObjectId] = None

created_at: datetime.datetime

updated_at: Optional[datetime.datetime] = None

expires_at: Optional[datetime.datetime] = None

policy: fiftyone.operators.store.models.KeyPolicy = 'persist'

static get_expiration(ttl: Optional[int]) → Optional[datetime.datetime]

Gets the expiration date for a key with the given TTL.

classmethod from_dict(doc: dict) → fiftyone.operators.store.models.KeyDocument

Creates a KeyDocument from a dictionary.

to_mongo_dict(exclude_id: bool = True) → dict

Serializes the document to a MongoDB dictionary.

class fiftyone.operators.store.KeyPolicy(value)

Bases: str, enum.Enum

Defines the eviction policy for a key in the execution store.

• PERSIST: The key is stored persistently and will never be automatically removed. It must be explicitly deleted.

• EVICT: The key is considered cacheable and may be removed automatically if a TTL is set, or manually via clear_cache().

Attributes:

PERSIST
EVICT

PERSIST = 'persist'

EVICT = 'evict'