History, previews and waiting

Where a value came from

EXPLAIN THING order_totals '1001';            -- the source rows behind key 1001, and each row's share
EXPLAIN THING order_totals '1001' LIMIT 50;

What changed a key

SHOW THING HISTORY order_totals '1001';

Each line has the time, the cause (for example lines update orderno 1001), and the values before and after. Two lines are kept per key; set AIOS_THINGS_HISTORY to keep more (up to 100,000).

The result at a past time

SHOW THING order_totals AS OF '2026-11-05 09:00:00';
SHOW THING order_totals AS OF '2026-11-05 09:00:00' KEYS ('1001', '1002');

History for AS OF is kept 30 days by default; change it with SET THING order_totals KEEP <n> DAYS. A time before the Thing existed is an error that says from when history is kept.

Preview a write

WHAT IF runs statements in a transaction that is always rolled back and shows how every Thing would change, including any action that would fire:

WHAT IF UPDATE lines SET picked = qty WHERE orderno = 1001;
WHAT IF 'DELETE FROM lines WHERE orderno = 1002; INSERT INTO lines (orderno, qty, picked) VALUES (1003, 1, 0)';

It cannot be used inside an open transaction.

Wait for a change

SHOW THING order_totals CLOCK;                 -- the Thing's change counter, say 42
WAIT THING order_totals SINCE 42 TIMEOUT 30;   -- returns as soon as the counter passes 42, or after 30 seconds

WAIT THING returns the new counter, the keys that changed, and whether the whole Thing was recomputed. The timeout is in seconds (default 30, up to 3600). Loop on it to follow a Thing without polling.

SHOW THING order_totals JSON SINCE 42 returns the rows changed since a counter value.