A count¶

Two kinds of answer come out of limma_facts, and they differ in kind.

mode="explore" is relevance-ranked retrieval. It finds things that look like your question and cannot tell you how many exist: a ranked list has no denominator. Use it to discover which addresses exist.
mode="enumerate" returns the closed set at an address you name in coordinate: every fact there, plus enumeration.exist — the count in the store BEFORE any page limit.

The pattern for a count you can act on: explore to find the address, then enumerate at it.

The enumeration block¶

r = client.post("/v1/public/facts", json={
    "workspace_id": WS, "question": "revenue", "mode": "enumerate",
    "coordinate": {"attribute": "revenue"}, "output_mode": "compact"})
body = r.json()
print(body["enumeration"])
print("completeness_licensed:", body["coverage"]["completeness_licensed"])
for fact in sorted(body["facts"], key=lambda f: f["period"]):
    print(fact["period"], fact["value_token"])

{'coordinate': {'attribute': 'revenue'}, 'exist': 3, 'delivered': 3, 'truncated': False, 'bound': True}
completeness_licensed: True
FY2022 1,100
FY2023 1,250
Q1 2024 312

field	meaning
`exist`	how many facts sit at this address in the store — the denominator
`delivered`	how many this response carries
`truncated`	`exist > delivered`: you hold a page
`bound`	the address resolved at all — decided on the attribute axis alone; see None versus Not recorded
`narrowed_by`	present only when the count ran over less than you can see, naming why. On either lane: `acl` (your key is scoped to some of the workspace's documents). On the relation lane (`relation_query`, see relations) also: `entities_not_recorded` (a workspace-wide query passed entities nobody loaded this relation for — name one with `entity_id` for its own verdict), `undated_rows` (an `active_in` query, or a `period_from` / `period_to` clause, passed rows with no `period_from`, which the date predicate cannot see), `open_period_rows` (a `period_to` clause needs the end of an open role past the month it was witnessed as held; `relations.period_unjudged.open_period` counts them), `open_period_rows_not_counted` (open roles the record says DO satisfy a `period_to` clause — witnessed as held past the bound — are not in `count`; `relations.period_unjudged.satisfied` counts them, and the search verb lists their entities as matches), `corrected_rows` (a document in scope still states a row a correction retired, so its true value is unrecorded — see corrections), `withheld_rows` (a connected export states a row of the relation that its loader could not read — a quarantined value, or a whole document it could tie to no entity — so the rows delivered are exact and there are no others is not; see a document-store export), `slot_unrecorded_rows` (rows that fail no clause but hold no value for a slot a clause names are not in `count` and not judged either way — over roles with no `industry` recorded, `industry eq X` and `industry ne X` are both unanswerable; `relations.slot_unrecorded` counts them per slot), and three from the vocabulary: `vocabulary_unbound:<slot>` (the clause on that term slot ran as written — its axis has no vocabulary, or a `ne` / `not_in` negates an ambiguous term — a closed set, but not the set you named; `relations.unbound_slots` lists them), `vocabulary_unknown_surface:<slot>` (a value you asked is no term of the axis and matched as written) and `vocabulary_unplaced:<slot>` (stored values no term places, or a catalogue fold on either side — see vocabulary). These eleven are the whole set on this verb; the search verb has its own list (search)

coverage.completeness_licensed is the one rule, computed in one place: true when the address is bound, the scope was not narrowed, and everything that exists was delivered — including when what exists is nothing. When it is false, coverage.withheld_because names why, and the reason is what tells you whether to page, widen your scope, or stop:

`withheld_because`	what happened	what to do
`truncated`	more exists than was delivered	page with `offset` / `limit`
`narrowed`	the count was taken over a subset of what you can see — it describes less than the question asked	read `narrowed_by`
`unaddressed`	the facts came from the ranked lane; ranking has no denominator	enumerate at an address
`unbound`	no address bound, so there is no set to be complete over	discover the name with `explore`; on the relation lane first read `relations.unbound_because` — `vocabulary_unbound:<slot>` is a comparison the workspace's vocabulary cannot order, not a misspelling (the `relations` and `relation_query` fields in the verb reference state the reasons)

A page says it is a page¶

r = client.post("/v1/public/facts", json={
    "workspace_id": WS, "question": "revenue", "mode": "enumerate",
    "coordinate": {"attribute": "revenue"}, "output_mode": "compact", "limit": 1})
body = r.json()
print(body["enumeration"])
print(body["coverage"]["completeness_licensed"], body["coverage"]["withheld_because"])

{'coordinate': {'attribute': 'revenue'}, 'exist': 3, 'delivered': 1, 'truncated': True, 'bound': True}
False truncated

A ranking says it is not a count¶

r = client.post("/v1/public/facts", json={
    "workspace_id": WS, "question": "revenue", "mode": "explore",
    "output_mode": "compact"})
body = r.json()
print(body["mode"], "| enumeration:", body["enumeration"])
print(body["coverage"]["completeness_licensed"], body["coverage"]["withheld_because"])

explore | enumeration: None
False unaddressed

What "exist" licenses¶

exist == delivered on a bound, unnarrowed address licenses the sentence these are all of them — over the documents your key can read, at this address, as the store names it. exist == 0 on a bound address licenses there are none.

It does not license:

that the values are right — read contested and the receipt on each fact;
that the address is the concept you meant — net_sales is unbound where the store says revenue (matched case-sensitively, surrounding whitespace trimmed — Revenue is unbound, revenue binds), and an unbound address is not a count of anything;
that the entity or period you named is spelled as the store spells it — binding is decided on the attribute axis alone, so {"entity": "Acme Corporation", "attribute": "revenue"} is bound and empty where the store says Acme Corp. Read the spellings off the closed set at {"attribute": ...} first (see None versus Not recorded);
anything about documents your key cannot read, or about a generation that has been superseded (retired generations are not in the count — see supersession).

Two facts at one address are not an error; they are the store reporting a disagreement. See contested.