Skip to the document

The record model

Neotoma separates a thing's stable identity from observations about it and the current view computed from those observations.

Source: docs/topics/architecture/record-model.md · Read Markdown · 08598d0

Four observations associated with one identity-bearing entity
The entity identity associates separate observations with the same thing.

Four useful objects

A source is recorded material, such as a file or an explicitly supplied piece of structured data. An observation states one or more fields about a target. An entity is the stable target: a person, company, task, document, or another declared type. A snapshot is the current field view computed for that entity. These objects have different jobs. A new observation may change a snapshot without changing the entity's identity or rewriting the source.

The common path for a file is source to interpretation to observation to entity snapshot. A structured write can also record an observation without a separately stored source file. Do not assume every observation has raw document bytes behind it; inspect the provenance on the row in question.

Why identity and state are separate

An entity ID identifies the logical target so observations from different submissions can refer to the same thing. The current name or status is an observed value and may change. Keeping the target separate from its current fields lets readers compare past and present assertions without treating each edit as a new thing.

Entity resolution and merges have their own rules. A field value resembling a person or company name does not guarantee that a new related entity or relationship was created. Inspect the resulting entity and graph rather than inferring those links from the input shape.

Read the current view

The reducer uses the declared entity schema and its per-field merge policies to choose current fields. That makes the snapshot a useful read surface, but the observations remain the durable evidence. A snapshot field should lead back to the observation that supplied it. If a field did not appear after a write, check the active schema and the stored observation before assuming the write changed the snapshot.

Read Observations for the evidence layer and Current snapshots for the derived view. The longer entity reference and snapshot reference describe their stored forms.

ObservationsInspect recorded claims, corrections, and source context.Current snapshotsSee how an entity's present fields are computed and traced.Schemas and field rulesCheck declared fields and the policies that select current values.Sources and provenanceTrace a current value back to recorded evidence.Inspect a changeCompare the current field with its observation history.