Skip to main content
An answer is the current materialized value of a judgment for a document. Answers come back inside documents and query rows, keyed by judgment name.
  • The numbers are the engine’s. p, dist and score are the engine’s raw output. Once a judgment has enough outcomes (100, with at least 20 of each kind) and a fit that beats the raw numbers on outcomes it was not fitted on, each answer also carries a calibrated object with the same fields plus stage (early while the fit rests on few outcomes, full once it rests on many), outcomes, from_previous_epoch and extrapolated. It never replaces the raw fields, and thresholds, filters and ranking use the raw fields. See calibration.
  • A composite judgment’s p is combined. It comes from weights fitted on your labels, and parts gives each part’s raw p. It has no calibrated object, and thresholds, filters and ranking use the combined p.
  • Every answer has provenance. It names the document revision it was computed for, the judgment_version, the engine_version and the evaluation_id, so you can always see how it was produced. When a change leaves the compiled context the same, the answer is reused for the new revision without calling the engine: revision moves on, and evaluation_id and evaluated_at still name the earlier evaluation that computed the numbers.
  • The answer of a judgment with relations has a watermark, the position in the namespace’s log its context was read at. Every write at or below it, to the document or to the documents that point at it, is reflected. revision still names the document’s own revision. For a relation that reads the document the judged one points at, the watermark also says which version of that document the answer read; an answer outside the judgment’s re-judge scope keeps that version after the document changes, and reads stale with stale_reason referenced_changed. On a get, such an answer also lists referenced_changes: the newest write to each document it points at that changed what the relation shows, with its revision and time. One at or below the watermark is in the answer; one above it makes the answer pending or stale inside the scope, and stale outside it. A failed answer of such a judgment keeps its last good numbers but has no watermark, because the failed attempt’s position does not describe them. A judgment with applies_to has no answer at all for the documents it does not apply to.
  • Relations add a few fields, each present only where it applies:
    • answers_generation, beside watermark: how far the context had read other judgments’ answers and block changes. Together they are the answer’s position; a roll-up’s child answer or a block change above either makes the answer pending or stale. Absent on a failed answer, like watermark.
    • referenced_changes[].deferred: true while that change’s fan-out waits past the judgment’s rolling limit, and referenced_changes[].generation when another judgment’s answer caused the change.
    • previous_revision, for a recipe with previous: the revision the previous rendering came from, absent when nothing was shown under previous. A failed answer keeps the last success’s.
    • For a choice that chooses among candidates, value is the matched document’s id or none_of_the_above, and dist lists only the candidates with any probability, and the escape.
  • Every answer has a freshness. stale and failed answers still carry the last good numbers and the revision they were computed for, and a stale one says why in stale_reason.
  • Numbers read as the decimals they are. Answers keep p, dist, score and escape_p to about seven significant digits and return each as the shortest decimal that stands for it, so an engine’s 0.01 reads 0.01, not 0.009999999776482582. Named thresholds, query filters and threshold recommendations all compare that decimal, so an answer that shows 0.01 meets a threshold of 0.01 everywhere.

​
Querying answers

Queries filter and rank on answers like any other field:
  • Filters are [field, op, value], ["And" | "Or", [...]] or ["Not", filter]. The operators are Eq, NotEq, In, NotIn, Lt, Lte, Gt, Gte, Glob, Contains (on string arrays) and Exists.
  • Filterable fields are id, revision, updated_at, attributes.*, and for each judgment p, value, score, dist.{option}, escape_p, freshness and thresholds.{name}. state is never filterable.
  • rank_by is one field and a direction, ["updated_at", "desc"] by default.
  • top_k is at most 1,000. A cursor from next_cursor fetches the next page. Cursors last 10 minutes and pin the namespace’s state, so pages are consistent with each other. more: true means more rows matched.
  • answers: "fresh_only" drops rows whose included answers are not fresh.
  • consistency: "eventual" may serve a view of the namespace up to 60 seconds old, for lower latency.
  • A query whose estimated scan is over 4 GB is refused with too_large and the estimate, and is not billed. Add attribute filters to narrow it.
You can filter or rank on any judgment except an on_read one, whose answers exist only once something reads them. on_change keeps every answer current, so it’s the policy to filter on; periodic and manual answers are filtered as they are stored. Using an on_read judgment in a filter returns invalid_request; switch it to on_change first, which backfills the missing answers after you confirm an estimate. Brussle never backfills silently.