Smart Cache

Smart Cache speeds up repeat loads of the same widget by storing the final widget result for a specific filter, sort, and query fingerprint. The next user requesting the same view gets the cached result instantly while AgenticBI quietly refreshes it in the background when it goes stale.

This is a separate layer from the direct-query cache (which lives at the connector level and stores raw query results). Smart Cache stores the post-processed widget result that AgenticBI was about to render - including filters, sorts, NLP, and post-processing applied.

Sections


How Smart Cache Works

When a user opens a widget, AgenticBI computes a fingerprint from everything that affects the result - dataset, query, filters, sorts, NLP, post-processors, share scope, and per-user content filters. If a previously stored result exists for that exact fingerprint, AgenticBI serves it directly.

Smart Cache uses a stale-while-revalidate model:

  • If the cached result is fresh, the user sees it immediately.
  • If the cached result is stale (the widget or its dataset changed), the user still sees the stale result immediately, with a small indicator showing it is refreshing. AgenticBI then fetches a fresh result in the background and updates the widget when ready.

This means dashboards stay responsive even on slow underlying queries - first viewer triggers the work, everyone after gets the cached answer until the upstream data or widget definition changes.

Smart Cache does not cache results that load quickly. By default, only widgets that take longer than a configurable threshold (3 seconds out of the box) are eligible for caching. Fast widgets execute live every time.


Per-Widget Settings

Individual widget owners can disable Smart Cache on a per-widget basis. This is useful when:

  • A widget shows real-time data and must always run live.
  • A widget queries a sensitive dataset where you do not want results stored on AgenticBI's side, even temporarily.

To disable Smart Cache for a single widget:

  1. Open the widget's analyze view.
  2. Click the Visualization tab.
  3. Under Advanced Settings, uncheck Smart Cache.
  4. Save the widget.

When unchecked, that widget always loads live regardless of the minimum duration threshold.


Direct Queries and Smart Cache

Smart Cache and direct-query cache are separate layers. A direct query is a query that AgenticBI runs against your live datasource on demand, rather than against a stored snapshot. Each direct query has its own cache duration setting (configured on the query itself).

Smart Cache respects your direct-query intent:

  • If a direct query has cache duration > 0, it opts into result caching, and Smart Cache may also cache the post-processed widget result for additional speedup.
  • If a direct query has cache duration = 0 (no cache), Smart Cache is also disabled for any widget that uses that query. This honors the "do not store results on AgenticBI's side" intent of direct queries with caching turned off.

When viewing a widget settings panel for a direct-query widget with no direct-query cache, the Smart Cache checkbox is disabled and shows the message: Unavailable because this direct query is configured with no direct-query cache.


Cache Indicators

Each widget shows a small indicator next to its title that reflects the cache state of the data being displayed:

  • Hit - The widget is showing a fresh cached result.
  • Stale (refreshing) - The widget is showing a cached result while a fresh one loads in the background. The widget will update automatically once the refresh completes.
  • Miss - The widget loaded live (no cache entry was usable).
  • Bypassed - The cache was skipped (for example, during an export or because Smart Cache is disabled).

Hovering over the indicator shows the last refreshed time so you can see how recent the displayed data is.


When the Cache Refreshes

AgenticBI automatically invalidates a widget's cache entries when any of the following change:

  • The widget itself is saved (visualization, filters, sort, NLP, etc.).
  • The widget is deleted.
  • The widget's filter settings are updated.
  • The widget's dataset is changed or deleted.
  • The widget is moved to a different dataset.

Invalidated entries are marked stale: the next viewer still gets an instant response from the stored entry while a fresh load runs in the background. Once the background refresh completes, every subsequent viewer sees the updated result.

Smart Cache also automatically expires cache entries after a configurable retention window. Old entries are cleaned up by a background janitor process, so storage stays bounded.


What Is Not Cached

The following always run live and never read from or write to Smart Cache:

  • Exports (PDF, CSV, Excel, scheduled reports).
  • Widget previews while editing a widget in the analyze view.
  • Widgets that load faster than the configured minimum duration.
  • Widgets explicitly disabled via the per-widget Smart Cache toggle.
  • Direct queries with no direct-query cache (see Direct Queries and Smart Cache).


Security and Sharing

Smart Cache is scope-aware. Two users in the same organization with different access - different content filters, different secure-share links, different drilldown context - each get their own cache entries. AgenticBI will never serve User A's filtered result to User B, even if the underlying widget and base query are identical.

In particular, the cache fingerprint includes:

  • The authenticated user's content filters and per-user constraints.
  • Secure-share scope (URL token + per-link content filters).
  • Dashboard and drilldown filters applied at view time.
  • Incognito session identity for shared dashboards.

If you use secure-share links with viewer-specific content filters, each filter combination is cached separately so distinct viewers cannot collide on the same fingerprint.


Troubleshooting

"I changed the dataset but old data is still showing."

The cache invalidates automatically when datasets change, but the first viewer after the change still sees the stale entry while the refresh runs in the background. Refresh the page once or twice and the new data should appear. The indicator will show Stale (refreshing) in the meantime.

"I want to force a fresh load right now."

Use the Refresh option from the widget's menu (...) on the dashboard. This bypasses the cache for that load and forces a live query.

"The Smart Cache toggle is missing from my widget settings."

This can happen if the widget uses a direct query with no direct-query cache. See Direct Queries and Smart Cache.