Freshness states
Freshness is worked out when the answer is read, from the answer, the document and the judgment’s policy. The first row that applies wins:
For a judgment with related documents, “the document changed since the answer” means that a write after the answer’s
watermark touched it: a write to the document itself, or to a document that pointed at it before or after the write. So a new ticket makes its account pending, and the account is fresh again once an answer lands with a watermark at or above the ticket’s write.
stale and failed answers still carry the last good numbers and the revision they were computed for. A failed answer for a document that was never judged successfully has no numbers. The next write to a document starts a new attempt, so failed gives way to pending or stale. A document that failed for a reason of its own, or is still failing 24 hours after it last changed, keeps its failed answer until it is written again, rather than being retried; see evaluations.
To read only fresh answers, pass answers: "fresh_only" to a query. To wait for an answer after a write, pass wait_for to the write; an answer not ready when it times out comes back pending in the write’s response, whatever this table would say on a get. To wait on a read, pass wait_ms (at most 10,000) to a get.
Freshness policies
A judgment’s policy decides when its answers are computed. It is a setting: changing it creates no new version.
Any policy can set
debounce_ms. A document that changed more recently than that is not judged until it settles, so a burst of writes costs one evaluation. Any policy can also set max_wait_ms, the ceiling: a document that never settles is still judged once that long has passed since its oldest unjudged change. It defaults to 12 × debounce_ms for a judgment with related documents and a debounce_ms above 0, and to none otherwise. Rapid writes to one document also coalesce: twelve changes in a second are judged once, on the latest revision.
A get of a document with on_read judgments starts their evaluation. The first read returns them pending, unless it passes wait_ms.
See choosing a freshness policy for the cost of each.