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 the database.
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 Entity state model
In the Value Entity model, only the current state is persisted. 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 Entity state model
The Event Sourced Entity model captures changes to data by storing events in a journal. 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 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
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 Entity model is most suitable. The entity state is stored as a single unit.
If you require a system that captures changes to data and allows for auditing or replaying events, the Event Sourced Entity model is a good choice. It ensures data integrity and consistency by storing events in a journal.
If you require high availability and low latency access to your entity data across multiple instances, the Replicated Entity model using CRDTs is a suitable option. It provides eventual consistency while allowing independent and concurrent state updates.
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.