8. Past states and history
on <collection> as of "<ISO date or datetime>" | …
on <collection> as of <generation> | …
on <collection> history | …
History needs a store that keeps it: OGD_HISTORY=on (memory and glacier backends). Without it, both forms fail with
this store does not keep history.
8.1 as of
Definition. Reads the store as it was at a time or at a commit generation.
on orders as of "2026-09-01T12:00:00Z" | where status == "paid" | count
on orders as of 1842 | sort total desc | limit 10
on orders as of "2026-09-01" | into orders_restored -- restore a past state
Behavior
as of <string>: the state after the last commit made at or before that time (ISO 8601; a date alone means midnight UTC).as of <number>: the state at that commit generation.- Every collection of the query is read at that point,
lookupandunioncollections included. - A date after the last commit reads the current state.
- Cost: the current state minus the documents changed since, plus the versions they had then. A collection not changed since reads at full speed.
Errors
- A generation after the current one, or before the start of the kept history.
- A date before the first recorded commit time.
as ofwithout a value keeps its old meaning: an alias namedof(on users as of | where of.age > 3).
8.2 history
Definition. One row per stored write of the collection, in commit order.
on orders history | where _doc_id == "0190f3c2-…" | sort _generation
on users history | where _op == "delete" and _at >= "2026-10-01" | select _doc_id, _by, name
Each row holds the document of that version, plus:
| Field | Meaning |
|---|---|
_id | Identifier of the history row (commit generation and position): distinct and ordered |
_doc_id | Identifier of the document |
_version | Version written (or deleted, for a delete row) |
_op | insert (version 1), replace, delete (the row holds the document as it was), baseline (present when history recording started) |
_generation | Commit generation |
_at | Commit time (ISO 8601), null when not recorded |
_by, _by_device | Identity and device of the commit, null when unknown |
These names replace document fields of the same name. Other collections of the query (lookup, union) are read
in their current state. history reads every stored version of the collection.
8.3 Rules for both
- Read-only: a writing stage is refused, except a terminal
into, which copies the rows into another collection (a restore). - A Place or App instance scope applies to every version, through its
_place/_app_instancefields.