cache

Cache module results for a specified duration.

Syntax

result = Module(args) with cache: <duration>

Type: Duration (ms, s, min, h, d)

Description

The cache option enables result caching for a module call. When enabled, the first successful call stores its result, and subsequent calls with the same inputs return the cached value until the TTL (time-to-live) expires.

The cache key is computed from the module name and all input values, ensuring that different inputs produce different cache entries.

By default, results are cached in-memory. Use cache_backend to select a distributed backend (Memcached, Redis, etc.) or set a global default via ConstellationBuilder.withCache().

Only cache pure functions

Caching is only safe for modules where the same inputs always produce the same outputs. Avoid caching modules with side effects or time-dependent results (e.g., GetCurrentTime).

Retry happens before caching

When combined with retry, the module is retried until success (or exhaustion), and only the final successful result is cached. Errors are never cached.

Examples

Basic Caching

profile = LoadUserProfile(userId) with cache: 15min

Cache user profiles for 15 minutes.

Short Cache for Fast Lookups

config = GetConfig(key) with cache: 30s

Brief caching for frequently accessed configuration.

Long Cache for Static Data

schema = LoadSchema(tableName) with cache: 1d

Cache schema definitions for a full day.

Cache with Retry

data = FetchData(id) with retry: 3, cache: 10min

Retries happen before caching. Only successful results are cached.

Cache with Distributed Backend

session = LoadSession(token) with cache: 1h, cache_backend: "memcached"

Use a named Memcached backend instead of the default in-memory cache. See cache_backend.

Behavior

1. Generate cache key from module name and input values
2. Check cache for existing entry
3. If cached value exists and not expired:
   • Return cached value (cache hit)
4. If no cached value or expired:
   • Execute the module (with retry if configured)
   • If successful, store result in cache with TTL
   • Return the result

Cache Key Generation

Cache keys are deterministic hashes of:

• Module name
• Input parameter names and values (sorted alphabetically)

This ensures:

• Same inputs always produce the same cache key
• Different inputs produce different cache keys
• Order of parameters doesn't matter

Duration Units

Unit	Suffix	Example
Milliseconds	ms	500ms
Seconds	s	30s
Minutes	min	5min, 15min
Hours	h	1h, 24h
Days	d	1d, 7d

Cache Statistics

The runtime tracks cache statistics using the unified CacheStats type:

Field	Description
hits	Number of cache hits
misses	Number of cache misses
evictions	Number of expired/evicted entries
size / entries	Current number of cached entries
hitRatio / hitRate	Ratio of hits to total accesses (0.0–1.0)

Access via the /metrics endpoint:

curl http://localhost:8080/metrics | jq .cache

Related Options

• cache_backend — Specify a named cache storage backend
• retry — Retry before caching result
• timeout — Timeout before caching result

Related Pages

• CacheBackend SPI — Implement a custom cache backend
• Memcached Module — First-party distributed cache via Memcached

Best Practices

• Cache expensive or slow operations
• Use shorter TTLs for frequently changing data
• Use longer TTLs for stable reference data
• Consider cache invalidation strategies for critical data
• Monitor cache hit rates to tune TTL values
• Only cache pure functions (same inputs = same output)