# What is an Entity?

The whole concept of Tilores resolves around an entity. An entity typically
represents an object in the real world. It could be something like a person, a
company, a group of financial transactions or even a molecule structure. If it
exists, it can be modeled as an entity.

## Real World Modeling Issue

The issue with modeling real world objects is that on one side, the amount of
data can be huge and on the other side, despite its size, the data is incomplete.

Let's assume our entity represents a person. We may have data about the same
person from various sources, with varying quality. We might have data about
different addresses, various variants of their name, e-commerce orders and/or
bank transactions. However, what we most likely do not have is a common identifier
of that person, e.g. a social security number or a passport id attached to all
those bits of information.

In Tilores these individual data pieces are called [records](schema.md#record).
Each entity comprises at least one record. Multiple records are automatically
matched together by [rules](rules/index.md) that you defined.

## Entity-ID and Entity Changes

Each entity in Tilores has an ID - a random UUID to be more precise. It will
be generated as soon as the first record has been submitted and that record does
not match with other existing entities. As more and more records for the same
entity are added, that ID is guaranteed not to change. However, there are situations
in which this promise cannot be upheld.

### Merging Entities

The most common scenario is that two (or more) entities will be merged. This is
typically the case when separate entities were created and then a new record
is received that connects these entities with each other. For person entities
this could be the case when, for example, John Smith and Jim Smith are actually the same
person (John-Jim Smith). When merging entities, only the most relevant
entity ID is preserved (typically the ID that was created first).

### Splitting Entities

When deleting records or entities, either due to explicit removal or due to
data expiry, it might happen that the only edges that connect two (or more)
parts of the same entity were removed. In that case each part will be a new
entity. Still we try to preserve the original entity ID and assign it to one of
the resulting entities - typically the one with the most data in it.

### Deleting Entities

When all data from an entity was removed, then that entity and therefore its ID
is also removed. Adding a record that would have matched with the original
entity if it still existed, will not restore the original entity ID, but create
a new entity ID.