Entity state models
Entities are used to store data, and they follow a specific state model chosen by the developer. The state model determines how the data is organized and persisted. Each entity has various data fields that hold different types of information. For example, in a weather system entity, the data fields could include temperature and air quality. In a warehouse entity, the fields might represent product names and inventory levels. Similarly, for customer entities, fields like email addresses and phone numbers are used. These fields can be simple or primitive types like numbers, strings, booleans, and characters. Alternatively, if needed, the fields can be more complex, which allows custom types to be stored in Kalix.
Entities have operations that can change their state. These operations are triggered by clients and implemented in the business logic. Some examples of these operations include updating the temperature in a weather system entity, adding inventory to a warehouse entity, or setting an email address for a customer entity. These operations allow entities to be dynamic and reflect the most up-to-date information.
Kalix supports different state models: Value Entity, Event Sourced Entity, and Replicated Entity. Value Entities store their state as a single unit in a Key/Value store. Event Sourced Entities store updates as events, which together build the entity’s state. Replicated Entities use a conflict-free replicated data type (CRDT) to distribute state across multiple instances, providing eventual consistency and low latency access.
Each Entity instance has a unique id that distinguishes it from others. The id can have multiple parts, such as an address, serial number, or customer number. Kalix handles concurrency for Entity instances by processing requests sequentially, one after the other, within the boundaries of a transaction. Kalix proactively manages state, eliminating the need for techniques like lazy loading. For each state model, Kalix uses a specific back-end data store, which cannot be configured.
The Value state model
In the Value state model, only the current state of the Entity is persisted - its value. Kalix caches the state to minimize data store access. Interested parties can subscribe to state changes emitted by a Value Entity and perform business actions based on those state changes.
The Event Sourced state model
The Event Sourced state model captures changes to data by storing events in a journal. The current entity state is derived from the events. Interested parties can read the journal and transform the stream of events into read models (Views) or perform business actions based on events.
The Replicated 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
When choosing a state model for your entities in Kalix, it is important to consider the specific requirements and characteristics of your application.
When you need a simple and straightforward approach, the Value state model is most suitable. The entity state is stored as a single unit. Use Kalix Value Entities. The Value state model generally requires less code then the Event Sourced state model, as commands directly modify the entity state.
If you require a system that captures changes to data and allows for auditing or replaying events, the Event Sourced state model is a good choice. It ensures data integrity and consistency by storing events in a journal. Use Kalix Event Sourced Entities.
If you require high availability and low latency access to your entity data across multiple instances, the Replicated state model using CRDTs is a suitable option. It provides eventual consistency while allowing independent and concurrent state updates. Use Kalix Replicated Entities.
Always consider the scalability, performance, and data consistency requirements of your application to make an informed decision about the state model that best suits your needs.
Next steps
Choose a state model for your first entity and get started using one of the SDKs:
Not sure which SDK to start with? We suggest the Java SDK which is the only one supporting a code-first development approach at present.