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 Knowi 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 Knowi was about to render ? including filters, sorts, NLP, and post-processing applied.

Sections


How Smart Cache Works

When a user opens a widget, Knowi 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, Knowi 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. Knowi 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.


Org-Level Settings

Org admins control Smart Cache for the entire workspace from User Settings ? Smart Cache.

To enable or disable Smart Cache org-wide:

  1. Click your user avatar in the top-right corner.
  2. Click Settings.
  3. Under Smart Cache, click Edit.
  4. Toggle Smart Cache on or off.
  5. (Optional) Set the Minimum query duration for a widget to be eligible for caching. The valid range is 2 to 300 seconds. Widgets that load faster than this threshold will not be cached. Default is 3 seconds.
  6. Click Save.

Disabling Smart Cache at the org level immediately stops new cache writes and prevents existing cache entries from being served. Knowi falls back to live loads for every widget request. Existing cache rows are cleaned up by the background janitor.


Per-Widget Settings

Individual widget owners can override the org-level setting 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 Knowi's side, even temporarily.

To disable Smart Cache for a single widget:

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

When unchecked, that widget always loads live. The org-level setting and minimum duration threshold no longer apply to it.

Note: If your org admin has disabled Smart Cache org-wide, the per-widget toggle does not appear. You cannot turn Smart Cache on for a widget when the org-level setting is off.


Direct Queries and Smart Cache

Smart Cache and direct-query cache are separate layers. A direct query is a query that Knowi 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 Knowi'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

Knowi 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. Knowi 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 means your org admin has disabled Smart Cache at the org level. Contact your admin or visit Settings ? Smart Cache if you have admin access.

"I'm an admin ? how do I clear all cached widgets at once?"

Disabling Smart Cache org-wide stops the cache from being served and the background janitor cleans up the rows. Re-enable to start caching again. There is no manual "purge all" button.