Glossary of Terms

Action

A serverless function that is executed based on a trigger. The trigger could be an HTTP or gRPC request or a stream of messages or events.

CI/CD

You can deploy Services using a Continuous Integration/Continuous Delivery service. See Integrate with CI/CD tools for instructions.

Code-first development

A style of developing Kalix services in which you are able to start by modeling your data model and API using the regular tools available for the specific language as opposed to describing the API with protobuf. See API description section.

Component

The SDKs support Entity, View, Action and Workflow components. These components enable you to implement your business logic.

Command

A command comes from a sender, and a reply may be sent to the sender. A command expresses the intention to alter the state of an Entity. A command is materialized by a message received by a Service implementation. Commands may come from outside the Kalix service, perhaps from other stateful services running on Kalix or from external systems, or they may come from within the service, invoked as a side effect or to forward command handling from another command. Commands are not persisted. A command might fail.

Command handler

A command handler is the code that handles a command. It may validate the command using the current state, and may emit events as part of its processing. A command handler must not update the state of the entity directly, only indirectly by emitting events. If a command handler does update the state, then when the entity is passivated (removed from memory), those updates will be lost.

Effect

From a Command handler a Component may notify other components by emitting effects. Effects trigger commands on other components, but do not affect the originating command. (To give a different component the responsibility to reply to the originating command, use a Forward.)

Entity

You implement one or more entities that are bundled into a Service implementation. An entity is conceptually equivalent to a class, or a type of state. An entity will have multiple Entity instances, each of which has a unique ID and can handle commands. For example, a service may implement a chat room entity, encompassing the logic associated with chat rooms, and a particular chat room may be an instance of that entity, containing a list of the users currently in the room and a history of the messages sent to it. Entities cache their state and persist it using Events.

Entity instance

An instance of an Entity, which is identified by a unique Entity key. An entity holds state in the Service implementation, and this state is held within the context of a gRPC stream.

Entity key

Deprecated name for the Component id.

Component id

An id used to identify instances of a stateful components like Entity or Workflow. All Commands must contain the component id so that the command can be routed to the right instance of the component that the command is for. The gRPC descriptoFr annotates the incoming message types for the component to indicate which field(s) contain the id.

Entity type

The type of state management that an Entity uses. Available types include Event Sourced Entity and Value Entity. Each type has its own sub protocol that it uses for state management, to convey state and updates specific to that type.

Event

An event indicates that a change has occurred to an entity and persists the current state. Events are stored in a journal, and are read and replayed each time the entity is reloaded by the Kalix state management system. An event emitted by one service might be interpreted as a command by another.

Event handler

An event handler is the only piece of code that is allowed to update the state of the entity. It receives events, and, according to the event, updates the state.

Event Sourced Entity

A type of Entity that stores its state using a journal of events, and restores its state by replaying that journal. These are discussed in more detail in Event Sourced state model.

Forward

A Component's Command handler may forward command processing to another component by issuing a forward. The target component’s reply will become the originating commands reply.

gRPC

A Remote Procedure Call framework developed by Google that provides high-performance communication between services. By default, gRPC uses Protocol Buffers (or Protobuf for short) for language-neutral serialization. As a developer, you write one file (.proto) that specifies the contract of your service containing the input, output, and operations. External consumers will use the contract to know how to call your service.

Journal

Persistent storage for Events from Event Sourced Entitys. Some documentation uses the terms Event Log or Event Store instead of journal. Kalix handles event storage for you, relieving you of connecting to, configuring, or managing the journal.

Kalix service

A Kalix service is a deployable unit. It is represented in Kubernetes as a KalixService resource. It contains a Service implementation and a Runtime. The Kalix operator transforms a kalix service into a Kubernetes Deployment resource and defines a Kubernetes Service to expose the kalix service to the outside world.

Kalix store

A kalix store is an abstraction over a data store, typically a database. It is represented in Kubernetes as a KalixStore resource. Kalix manages the stateful store for you.

Replicated Entity

A type of Entity that stores its state using a Conflict-free Replicated Data Type (CRDT), which is replicated across different instances of the service. These are discussed in more detail in Replicated Entities.

Protocol-first development

A style of developing Kalix services in which you start by defining your API and data models using protobuf and then, making use of our code generators you are able to follow-up and provide specific domain implementations. See API description section.

Runtime

When you deploy a Service, Kalix deploys a Runtime along with it. The runtime manages entity state, and exposes the service implementation to the rest of the system. It translates incoming messages to commands and sends them to the service. The runtime also forms a cluster with other instances of the same service, allowing advanced distributed state management features such as sharding, replication and addressed communication between instances.

Service

A service is implemented by a Kalix SDK. At runtime, Kalix enriches the incoming and outgoing gRPC messages with state management capabilities, such as the ability to receive and update state. You implement the business logic for the service, which includes stateful entities. You deploy your services to Kalix and Kalix adds a Runtime that handles incoming communication and persistence at runtime.

Service implementation

A service implementation includes the logic that you write for stateful entities. You package a service as a Docker image, and Kalix deploys it as a Kalix service.

Snapshot

A snapshot records current state of an Event Sourced Entity. Kalix persists snapshots periodically as an optimization. With snapshots, when the Entity is reloaded from the journal, the entire journal doesn’t need to be replayed, just the changes since the last snapshot.

State

The state is simply data—​the current set of values for an entity instance. Event Sourced Entities hold their state in memory.

State model

Each entity uses one of the supported state models. The state model determines the way Kalix manages data. Currently, these include Value Entity, Event Sourced Entity and Replicated Entity.

Timer

A Timer provides consistent scheduling and execution of a call to another Component at specified intervals or delays. They are convenient for automating repetitive work and handling timeouts within business logic implementation.

Value Entity

A Value Entity stores state in an update-in-place model, similar to a Key-Value store that supports CRUD (Create, Read, Update, Delete) operations. In Domain Driven Design (DDD) terms, a Value Entity is an "Entity." In contrast with "Value Objects," you reference Entities by an identifier and the value associated with that identifier can change (be updated) over time. These are discussed in more detail in Value state model.

View

A View provides a way to retrieve state from multiple Entities based on a query. You can query non-key data items. You can create views from Value Entity state, Event Sourced Entity events, and by subscribing to topics.

Workflow

Kalix Workflows are high-level descriptions to easily align business requirements with their implementation in code. Orchestration across multiple services with support for failure scenarios and compensating actions is simple with Kalix Workflows. See Kalix Workflows.

Workflow Step

A Workflow definition element which encapsulates an action to perform and a transition to the next step (or end transition to finish the Workflow execution).