fiftyone.operators.cache.decorator#

Execution cache decorator.

Copyright 2017-2025, Voxel51, Inc.
voxel51.com

Functions:

execution_cache([_func, residency, ttl, ...])

Decorator for caching function results in an ExecutionStore.
fiftyone.operators.cache.decorator.execution_cache(_func=None, *, residency='hybrid', ttl=None, max_size=None, link_to_dataset=True, key_fn=None, store_name=None, version=None, operator_scoped=False, user_scoped=False, prompt_scoped=False, jwt_scoped=False, collection_name=None, serialize=None, deserialize=None)#

Decorator for caching function results in an ExecutionStore.

The function being cached must:

  • accept a ctx as the first parameter

  • be idempotent, i.e., same inputs produce the same outputs

  • have serializable function arguments and return values

  • have no side effects

Note

When residency != "ephemeral", cached values must be coerced to JSON safe types in order to be stored. By default, a default JSON converter is used that can handle many common types, but you can override this behavior if necessary by providing custom serialize and deserialize functions.

Examples:

from fiftyone.operators import execution_cache

# Default behavior: cache for the life of a dataset
@execution_cache
def expensive_query(ctx, path):
    return ctx.dataset.count_values(path)

# Cache in-memory, and only while the current operator prompt modal is open
@execution_cache(prompt_scoped=True, residency="ephemeral")
def expensive_query(ctx, path):
    return ctx.dataset.count_values(path)

# Cache with a custom TTL and store name
class Processor:
    @execution_cache(ttl=60, store_name="processor_cache")
    def expensive_query(self, ctx, path):
        return ctx.dataset.count_values(path)

#
# Cache at the user-level
#

def custom_key_fn(ctx, path):
    return path, ctx.user_id

@execution_cache(ttl=90, key_fn=custom_key_fn, jwt_scoped=True)
def user_specific_query(ctx, path):
    return ctx.dataset.match(F("creator_id") == ctx.user_id).count_values(path)

#
# You can manually bypass/modify the cache if necessary
#

# Bypass the cache
result = expensive_query.uncached(ctx, path)

# Set the cache for the given arguments
expensive_query.set_cache(ctx, path, value_to_cache)

# Clear the cache for a specific input
expensive_query.clear_cache(ctx, path)

# Clear all cache entries for the function
expensive_query.clear_all_caches()
expensive_query.clear_all_caches(dataset_id=dataset._doc.id)
Parameters:

  • residency ("hybrid") –

    the residency of the cache. Can be one of:

    • "transient": the cache is stored in the execution store with policy="evict"

    • "ephemeral": the cache is stored in memory and is cleared when the process ends

    • "hybrid" (default): a combination of transient and ephemeral. The cache is stored in memory and in the execution store. The memory cache is used first, and if the value is not found, it falls back to the execution store

  • ttl (None) – a time-to-live for cached values, in seconds

  • max_size (None) – a maximum size for ephemeral caches. The default size is 1024. The cache will evict the least recently used items when the size exceeds this limit

  • link_to_dataset (True) – whether to namespace cache entries to the current dataset. If True, any cached values are automatically deleted when the dataset is deleted

  • key_fn (None) – a custom function to generate cache keys. By default, the function arguments are used as the key by serializing them as JSON

  • store_name (None) – a custom name for the execution store backing the cache. Defaults to the function name

  • version (None) – a version number to prevent cache collisions when the function implementation changes

  • operator_scoped (False) – whether to tie the cache entry to the current operator

  • user_scoped (False) – whether to tie the cache entry to the current user

  • prompt_scoped (False) – whether to tie the cache entry to the current operator prompt

  • jwt_scoped (False) – whether to tie the cache entry to the current user’s JWT

  • collection_name (None) – override the default collection name for the execution store used by the cache. The default is "execution_store"

  • serialize (None) – a custom serialization function to use when caching values and function arguments

  • deserialize (None) – a custom deserialization function when retrieving cached values

IN THIS ARTICLE