Insights & memory

An insight is an answer the organization keeps: the question in plain language, the SQL that answered it, the result itself, and a pin to the exact data versions it was computed from. It is the memory contract — a conclusion that is governed, reproducible, and knows when it has gone stale.

Create, replay, refresh

CREATE INSIGHT top_denial_driver QUESTION='What drives denials?' AS
    SELECT DENIAL_REASON, COUNT(*) N FROM HEALTH.CORE.FCT_CLAIM
    WHERE IS_DENIED = 1 GROUP BY 1 ORDER BY N DESC;

SHOW INSIGHTS;                                     -- with freshness
SELECT * FROM TABLE(INSIGHT('top_denial_driver')); -- the pinned answer
REFRESH INSIGHT top_denial_driver;                 -- recompute and re-pin
DROP INSIGHT top_denial_driver;

TABLE(INSIGHT('name')) returns the stored answer and composes in real SQL — filter it, join it, chart it. The result is byte-identical on every read until the inputs change.

Freshness is a fact, not a guess

Because tables are immutable version chains, ObeliskDB computes freshness by comparing an insight's pinned versions to the live ones:

• - current — every pinned table is still at its pinned version.
• - stale — a source table has advanced; re-running may differ.
• - invalidated — a pinned table no longer exists.

Freshness is also pushed: when a write commits a new version of a table, any insight pinned to it is marked stale at write time and an event is recorded — you don't wait until the next read to discover it.

Governed on read

Reading a stored answer requires a role at least as privileged as the one that computed it. A conclusion drawn under ACCOUNTADMIN will not open for an analyst, so insights never leak data across a masking boundary that the underlying query would have stopped. See Governance.

Obi uses insights as memory

Obi checks find_insights before recomputing an analysis and offers save_insight after a notable one, so the organization accumulates answers instead of re-deriving them. Search is semantic (local embeddings) with a keyword fallback — a question finds a matching insight by meaning, not just wording. The console's Insights view lists every insight with its freshness and lets you view, refresh, or drop it.

Verified-query reuse

verified_sql(question) returns the governed SQL of the closest saved insight when a natural-language question is similar enough — so an agent reuses a vetted query instead of regenerating one. Available as an Obi tool and over MCP.

Standing questions

Compose insights with tasks and platform agents and a dashboard becomes an answer something keeps true:

CREATE TASK keep_fresh WAREHOUSE=COMPUTE_WH SCHEDULE='60 MINUTE'
    AS REFRESH INSIGHT top_denial_driver;

The shipped Insight Keeper platform agent sweeps periodically, refreshing stale insights and reporting which answers materially changed.