Three words
A record is a JSON document with an id, living in a collection.
A collection is a named set of records on a branch. You define it once, with or without a schema.
A version is a point in a branch’s history, written as a generation and a sequence.
{ "generation": "3", "sequence": "41" }Nothing is edited in place
Writing record p0 twice makes two versions of p0. Deleting it adds a deletion. A reader who asks for a retained earlier version sees the record as it was then. A released version is refused by name.
The read_history tool reads either a branch’s retained snapshots or one record at a captured version.
Expected versions
Every write carries the version the writer believes the branch is at. The service checks it before applying anything.
If the branch has moved, the write is refused by name and nothing is written. This is how two people, or a person and an agent, write to the same branch without overwriting each other.
Relations and vectors
A relation declares endpoint collections and cardinality. An edge links two records under that relation, with properties. The match stage walks those edges.
A vector is a numeric field declared on a collection. The similar and rerank stages read it.
Deleting a record also removes the relations and vectors attached to it.
Where old versions go
History release removes versions permitted by the retention policy. Reclaim then removes storage that no branch, snapshot or pin can reach. Read History and time before choosing that policy. See Reclaim.