Index Overview

What the Deal Index Is

The index stores three kinds of thing, and most confusion comes from mixing them up.

• Fact — the canonical value for one metric on one entity, the NOI Lev will show you for this property. Identified by a sot_id.
• Observation — one value an extractor pulled from one document, with its file, page range, and confidence. A fact can have several, and one of them is promoted to canonical.
• Metric definition — an entry in the catalog of what is recordable at all, carrying the metric_id and value_type you need to write a value.

Facts attach to entities, not just to the deal. A deal has an entity for itself, one per property, and others for the sponsor, broker, and team members. A property metric such as in-place NOI belongs to a property: entity, not the deal: entity.

Endpoints

Read a Fact and Trace It

To answer "what is the NOI, and where did it come from":

1. Search for the fact. Call Search Index with a context describing what you want. Each result carries the canonical value, a sot_id, and a source block naming the document.
2. Pull its observations. Pass that sot_id to Index Observations to see every value extracted for that fact, one per document, with page ranges and confidence.
3. Request links only when you need them. Set include_signed_urls=true on either call to get short-lived download URLs for the source documents.

Record or Correct a Fact

Correcting a value the deal already has is a different path from recording one it has never had.

To correct an existing fact, search for it, then call Update Index Fact with its sot_id. Pass an observation_id to promote a value an extractor already found, which keeps the source document and page range attached. Pass a raw value only when no observation is right.

To record a new fact, look up the metric with Metric Definitions, look up the target with Index Entities, then post the pair to Insert Index Facts. Send an explicit entity_ref that matches the metric's entity type.

What Search Does Not Do

Search Index takes a natural-language context and returns ranked matches above a similarity threshold. It is not an export. A single call returns at most 200 facts and takes no offset, so there is no way to page through a deal's full index.