# Records, collections and versions

What a record is, how collections hold them, and why every write makes a new version instead of changing an old one.

A record is one JSON document with an id. A collection is a named set of records. A version is a point on a branch's history. Every change moves the branch to a new version, and retained old versions stay readable.

## 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.

**A version**

```json
{ "generation": "3", "sequence": "41" }
```


> Why strings
> Both numbers are carried as strings so that no client rounds them. Compare them as whole numbers.


## 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](/haematite/concepts/history-and-time/) before choosing that policy. See [Reclaim](/haematite/concepts/reclaim/).