Event Sourced Entity in Kalix

Reading Time: 3 minutes

What is an event sourced entity?

Before understanding event sourced entity, let’s first understand a few terminologies:

  • Entity – An entity is any singular, identifiable and separate object.
  • Command – Command is an instruction which a user gives to a computer or a program to perform a specific task.
  • State –  The state of a program is its condition regarding stored inputs. The term “state” is similarly to how we use in science — whereas the state of an object, for instance, as a gas, liquid or solid, shows its current physical makeup, the state of a computer program shows its current values or contents.

Now, let’s understand what is an event sourced entity. Consider an example where we have an entity, the entity receives some commands and it causes a state change which then causes the service to emit an event. The service will then receive the events and invoke the respective business logic which will then cause a state change.

Let’s also understand the difference between a command and an event. A command is a request for an operation which has not happened yet, for example – add item, delete item whereas an event is something which has happened in the past, for example – item added, item deleted.

How to create event sourced entities?

Let’s take an example of a voting-system where can create a new candidate and we can then vote for that candidate through an API endpoint. Let’s assume that the candidate has already been created and we are only going to vote for the candidate.

File structure


So, first we have to define the service. Line 2 is the kalix annotation for the code generation. Line 3 defines that it is an event_sourced_entity. Inside the entity, you have to define the name, entity_type, state and the events.

Then we define the API with rpc which we have defined on line 13 above. Note that it is optional to provide the API endpoint. If we don’t define an endpoint, then we make a direct call to the rpc.

And at last, we have to define the message which is an input to the rpc. You can see that we have defined the message on line 20 which is being used as an input on line 13 while defining the API.


CandidateState defined above is the object for the state which links to the object name we have defined in candidate_api.proto on line 6.

CandidateVoted defined above is the event object which links to the object name we have defined in candidate_api.proto on line 8.

After creating the above 2 files, when we compile the code using sbt compile, kalix auto-generate a few files which contains the methods without any implementation. We then have to write our own business logic by implementing those methods.

Below is how an auto-generated file looks like when we compile the code for the above 2 files.


It creates an emptyState method which is used to store an instance of the CandidateState, voteForCandidate method is invoked when the rpc is called to vote for the candidate, candidateVoted method is invoked when the service receives the CandidateVoted event.

Now, let’s implement the methods generated by kalix.

Now, emptyState contains an instance of CandidateState, voteForCandidate emits a CandidateVoted event and candidateVoted changes the state of the service.

This was all about event sourced entity. I hope you understood what is an event sourced entity and how we can create it.

Wanna know more about Kalix? You can go to docs.kalix.io and read the documentation.

Written by 

Bhavya Verma is a Software Consultant at Knoldus. An avid Scala programmer, he is recognised as a good team player, dedicated and responsible professional, and a technology enthusiast. He has good time management skills. His hobbies include playing badminton, watching movies and travelling.