Caching and freshness

ReportPlane uses caching for performance, but not every cache has the same purpose.

Query result cache#

Analytics bindings can define cache_ttl_seconds. Equivalent queries can reuse a result during that time according to runtime cache keys and policy.

In Redis mode, query results use the reportplane:query namespace. A Redis read/write failure does not prevent the warehouse query; it is logged and treated like a cache miss.

Runtime configuration snapshot#

Authorization and runtime configuration are stored in a process-local atomic snapshot. Each instance refreshes it from PostgreSQL at the configured interval.

This means a management write can succeed shortly before every runtime instance can see it. Newly created clients and analytics definitions may need a bounded retry.

Live and quota state#

Live metrics and quota counters use their own namespaces and timing. They do not control when a newly saved Analytics API appears in the local configuration snapshot.

Query-result cache identity includes the current canonical Analytics definition. Editing dimensions, metrics, filters, limits, visualization-independent execution rules, or latest_by therefore produces a new cache key instead of serving a result created for the previous definition.

Design your application for freshness#

• expect immediate consistency for the management response itself;
• tolerate a short eventual-visibility window on newly created runtime resources;
• use bounded retry with delay, not an infinite tight loop;
• understand a configured query TTL before expecting newly written warehouse data in an identical cached query;
• use a different filter/window or wait for expiry when validating fresh data.