State models

The state model of an entity determines how Kalix stores and manages its data. Choosing a state model impacts both how you implement the entity and its behavior at runtime. In contrast, the service API responds to commands that are independent of the entity state model.

Kalix supports Value Entity, Event Sourced Entity, and Replicated Entity state models:

Value Entities are Key/Value stores and offer the traditional approach to persistence-storing state as a single, complete unit.
Event Sourced Entities store each update as an event, which together build the state of the entity.
Replicated Entities distribute state using a conflict-free replicated data type (CRDT) which shares data across multiple instances to provide eventually consistent, highly available, low latency data access.

For all types of entities, Kalix manages concurrency. It processes requests to the same entity instance sequentially. The next request in line will not be processed until the state update from the previous command finishes.

Kalix proactively manages the state. You need not worry about "lazy loading" or other performance techniques. In other words, once an entity is active, Kalix does not need to re-fetch its state for every request.

For each state model, Kalix leverages a well-suited back-end data store. The data store type is not configurable.

The Value Entity state model

Value Entities only persist their current state. The following diagram shows how the Kalix proxy persists state for a Value Entity:

Concepts Value Flow

Once an entity with a particular ID has been instantiated, Kalix caches its state and subsequent requests can be satisfied without accessing the data store. After an entity has been idle for a period of time, Kalix passivates it to conserve resources.

The Event Sourced Entity state model

Event-sourcing involves capturing changes to data, as opposed to overwriting existing values. For example, a bank tracks account debits and credits, rather than just recording the balance. In case of an audit, a bank can reliably point to each transaction that led to the current balance. Similarly, in an event-sourcing system, the changes to data can be replayed in the case of failure, or when spinning up new services to handle load.

Kalix Event Sourced Entities store events in a journal. Different services can start reading the journal at different points. This results in what is called "eventual consistency." When all interested parties have read all the entries, the system is consistent—they all have the latest data. Before that, some parties might be behind for a short time, but they are guaranteed to catch up.

Concepts Events Source Flow

The Replicated Entity state model

Replicated Entities distribute state using a conflict-free replicated data type (CRDT). Data is shared across multiple instances of a Replicated Entity and is eventually consistent to provide high availability with low latency. The underlying CRDT semantics allow Replicated Entity instances to update their state independently and concurrently and without coordination. The state changes will always converge without conflicts, but note that with the state being eventually consistent, reading the current data may return an out-of-date value.

Choosing a state model

State Model	Benefits	Example
Value Entity	All entities are scalable, long-lived, addressable, and provide key/value access to the data of the entity.	Shopping carts, customer registries, any use case where only the last state is needed.
Event Sourced Entity	All entities are scalable, long-lived, addressable, and state-changing events are stored in a journal.	Inventory systems, bank transactions, any use case where you need both the current and historical state.
Replicated Entity	Eventually consistent, highly available, low latency data access.	Collaboration tools, synchronization tools, any use case where the same data can be modified in different places and needs to be made consistent.

State Model

Benefits

Example

Value Entity

All entities are scalable, long-lived, addressable, and provide key/value access to the data of the entity.

Shopping carts, customer registries, any use case where only the last state is needed.

Event Sourced Entity

All entities are scalable, long-lived, addressable, and state-changing events are stored in a journal.

Inventory systems, bank transactions, any use case where you need both the current and historical state.

Replicated Entity

Eventually consistent, highly available, low latency data access.

Collaboration tools, synchronization tools, any use case where the same data can be modified in different places and needs to be made consistent.

Value Entities give you the benefits of the Entity pattern in general: scalable, long-lived, addressable behaviors. Because Event Sourced Entities store state as a sequence of state-changing events, they offer extra benefits such as auditing, temporal queries to reconstruct historical state, and so on.

You may find Value Entities more straightforward to implement because you do not have to think about events. With Value Entities, you also have traditional database-like consistency. Event Sourced Entities are eventually consistent.

Both state models relieve you of writing the plumbing code normally required for data access.