Cache Management

oikapi uses a multi-level caching system to keep metadata lookups fast. As an admin, you can monitor cache performance and clear caches when needed.

Cache types

Cache	Max Size	TTL	Purpose
table	1,000	-	Table definitions
field	1,000	-	Field definitions
presets	1,000	-	Saved view/preset configurations
permissions	- (group)	- (varies)	Permission check results (facade over multiple sub-caches; sub-caches use 30 sec – 10 min TTLs)
resolved_field_access	5,000	5 min	Field access resolution
js_executor	1,000	-	Compiled JavaScript/TypeScript
effective_rules	1,000	30 sec	Effective business rules per table+trigger
webhook_rules	1,000	5 min	Webhook rules per webhook name
user_roles	10,000	5 min	User role assignments
user_teams	10,000	5 min	User team assignments
api_keys	10,000	5 min	API key validation
bm25_searchable_fields	1,000	10 min	Searchable field definitions per table
app_cache	1,000 per app	5 min	Per-application business rule cache
submissions	1,000	5 min	Public submission endpoint definitions
counter_metadata	unlimited	-	Counter/sequence metadata

Viewing cache stats

oi cache stats

Returns hit rate, size, hits, misses, and evictions for every cache.

Clearing caches

Clear all caches:

oi cache clear

Clear a specific cache:

oi cache clear permissions

Inspect cache entries (superuser-only endpoint):

oi api GET '/api/internal/caches/permissions/entries?limit=100&offset=0'

Note

Cache management endpoints require superuser-level access. On managed instances, contact our team if you need caches cleared — this is typically handled automatically.

Prometheus metrics

oikapi_cache_size{cache_type="table"}
oikapi_cache_hits_total{cache_type="table"}
oikapi_cache_misses_total{cache_type="table"}
oikapi_cache_evictions_total{cache_type="table"}

Troubleshooting

Stale data after changes: Clear the relevant cache. On multi-instance deployments, cache invalidation is handled automatically via pub/sub.

Low hit rates: May indicate high cardinality access patterns. Contact support if this persists.

High memory usage: Reduce cache max sizes or enable TTL-based expiration.