Certainty and Caching in Seeq — What an Integration Needs to Know¶
When Seeq draws a signal or a condition that comes from an external data source, it asks that source's connector for the data, and then it decides what to keep. The rule it follows is simple to state and easy to miss: Seeq caches what the connector reports as certain, and asks again for what it reports as uncertain.
There is no separate switch to turn caching off for an item. A cache can be cleared, through the Seeq API (Application Programming Interface), but not disabled. Seeq's reasoning is consistent: if a result must not be cached, then by definition it is not yet certain. So for an integration the real question is not "should Seeq cache this?" but "how far is this result final?"
For a historian that only ever appends data, the defaults are usually right. It matters more for an integration whose data can still change after Seeq first reads it: late or corrected values, results computed when Seeq asks, values from a system that keeps changing.
The mechanism: the last certain key¶
A connector answers each request with samples (for a signal) or capsules (for a condition). With that answer it can give Seeq a last certain key: a point in time at or before which nothing will change. Seeq then treats the data in two parts:
- At or before the key: certain. Seeq caches it and draws it normally. A later view of that time is served from the cache, without asking the connector.
- After the key: uncertain. Seeq draws it in its uncertain style and asks the connector again on a later view or refresh.
When the connector gives no key, Seeq applies its own default:
| Item | No last certain key means |
|---|---|
| Signal | certain up to the last sample in the answer; the time after it is uncertain |
| Condition | every capsule uncertain |
An open capsule, one still in progress, is uncertain until it ends.
Two rules govern how a key may change:
- Certainty only moves forward. Seeq remembers how far an item has been certain and rejects an answer that claims less ("Inconsistent cache detected … went back in time"). A key must stay where it is or advance; it may never move back.
- A change to less certainty needs a cache clear. An item that starts reporting less certainty than before, for example after its connector's configuration changes, has its cache cleared once through the API so Seeq accepts the new answers.
What Seeq does with each kind of answer¶
Three ways a connector can set the key cover most needs:
| The connector reports | Seeq caches | On a refresh, Seeq asks again for | Workbench draws |
|---|---|---|---|
| No key (Seeq's default) | everything up to the last sample | the time since the last sample | solid |
| A key trailing now by a period (now minus one hour, say) | everything older than that period | the last period | solid, then uncertain for the last period |
| A key that never advances (a fixed point in the distant past) | nothing | the whole range viewed | uncertain throughout |
In Workbench the uncertain style for a signal is a dotted line; the Certainty button on the trend toolbar switches the style on and off.
We tested each case live in Seeq Workbench. Two behaviors are easy to get wrong:
- "No key" does not mean "never asked again". A refresh still asks for the time since the last sample, because Seeq treats an answer as certain only up to there. For a data source that writes sparse or irregular samples, this tail can be long.
- A trailing key is measured from now, not from the range on screen. A day in the past is all certain and drawn solid; only the period before now is uncertain. A range Seeq has never been asked for is asked once, whatever the key.
Seeq's own guidance for historians uses the trailing key: if every value is known to arrive within three hours, the last certain key can be "now minus three hours".
How to choose¶
Ask how long the result can still change:
| The data | Report | What it costs |
|---|---|---|
| Final once written: the same request always gives the same answer | no key, or a key at the last sample | nothing: cached, fast |
| Can arrive late, or be corrected, for a known period | a key trailing now by that period | the last period is re-read on each refresh |
| Changes at any time, or must be recomputed on every view | a key that never advances | every view and refresh, by every user, asks the source |
Choose per result, not per system: one integration can serve all three. Choosing too certain shows a cached answer that has since changed, until the cache is cleared; choosing too uncertain re-reads data that will not change, on every view.
An example: our Seeq connectors¶
- In the Double Agent Connector for Seeq a request is answered by logic that runs when Seeq asks, and only that logic knows whether its answer can change. So each action, the logic a request selects, declares one of the three kinds as part of its definition, under names of our own: settled (no key), recent with a period (a trailing key), unsettled (a key that never advances). A connection can still be set to report everything as uncertain, for an operator who wants nothing cached. Every key it reports is constant or moves forward with time, so Seeq never rejects an answer.
- Our connectors that serve another system's data, such as the ABB Knowledge Manager connector, share one implementation of the last certain key in the VirtualForge connector SDK (Software Development Kit), with a mode for a fixed settling period and one for late-arriving data, so a data source that needs one gets it the same way in each.