# 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. Each entity comprises at least one record. Multiple records are automatically matched together by rules 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.