Simple projection

A projection in Cratis is a way to create read models from events in the event store. The simplest projection automatically maps event properties to read model properties with matching names using the default AutoMap behavior.

Defining a simple projection

A projection implements IProjectionFor<TReadModel> and defines its behavior in the Define method:

C#

using Cratis.Chronicle.Projections;

public class DecSimpleUserProjection : IProjectionFor<DecSimpleUser>
{
    public void Define(IProjectionBuilderFor<DecSimpleUser> builder) => builder
        .From<DecSimpleUserCreated>();
}

View C# snippet source on GitHub

Kotlin

import io.cratis.chronicle.projections.IProjectionBuilderFor
import io.cratis.chronicle.projections.IProjectionFor

class DecSimpleUserProjection : IProjectionFor<DecSimpleUser> {
    override fun define(builder: IProjectionBuilderFor<DecSimpleUser>) {
        builder.from(DecSimpleUserCreated::class)
    }
}

View Kotlin snippet source on GitHub

Java

import io.cratis.chronicle.projections.IProjectionBuilderFor;
import io.cratis.chronicle.projections.IProjectionFor;

class DecSimpleUserProjection implements IProjectionFor<DecSimpleUser> {
    @Override
    public void define(IProjectionBuilderFor<DecSimpleUser> builder) {
        builder.from(DecSimpleUserCreated.class);
    }
}

View Java snippet source on GitHub

Elixir

defmodule MyApp.Projections.DecSimpleUserProjection do
  use Chronicle.Projections.Projection, model: MyApp.ReadModels.DecSimpleUser

  alias MyApp.Events.DecSimpleUserCreated

  from DecSimpleUserCreated
end

View Elixir snippet source on GitHub

TypeScript

import { IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@projection()
class DecSimpleUserProjection implements IProjectionFor<DecSimpleUser> {
    define(builder: IProjectionBuilderFor<DecSimpleUser>): void {
        builder.from(DecSimpleUserCreated);
    }
}

View TypeScript snippet source on GitHub

This projection:

• Automatically maps properties from UserCreated event to the User read model (AutoMap is enabled by default)
• Uses the event source ID as the key for the read model
• Properties with matching names are automatically mapped

Note: AutoMap is enabled by default at the top level. You don’t need to call .AutoMap() explicitly unless you want to ensure it’s enabled in contexts where it might be disabled. Read more about auto mapping

Base event types in the .NET client

From<TEvent>() also accepts a base event type or an interface. It registers every known event type assignable to TEvent, including the base type itself when it is an event type. The same property mappings, key, and parent key apply to each event type, whether the registration is at the root, in a children collection, or in a nested object.

When a base or interface registration overlaps an explicit From<ConcreteEvent>(), their property mappings are combined. The explicit registration wins on conflicting properties and supplies the key and parent key, regardless of call order. Without an explicit registration, the first matching base or interface registration supplies the keys, while later inherited mappings win on conflicting properties. This does not subscribe to unrelated event types; use FromAll for that behavior.

Read model definition

The read model is a simple record or class representing the projected data:

C#

public record DecSimpleUser(string Name, string Email, DateTimeOffset CreatedAt);

View C# snippet source on GitHub

Kotlin

import java.time.OffsetDateTime

data class DecSimpleUser(
    val name: String = "",
    val email: String = "",
    val createdAt: OffsetDateTime? = null
)

View Kotlin snippet source on GitHub

Java

class DecSimpleUser {
    public String name = "";
    public String email = "";
    public String createdAt = null;
}

View Java snippet source on GitHub

Elixir

defmodule MyApp.ReadModels.DecSimpleUser do
  use Chronicle.ReadModels.ReadModel

  defstruct [:name, :email, :created_at]
end

View Elixir snippet source on GitHub

TypeScript

class DecSimpleUser {
    name = '';
    email = '';
    createdAt = new Date();
}

View TypeScript snippet source on GitHub

Event definition

The event should match the read model structure for auto-mapping to work:

C#

using Cratis.Chronicle.Events;

[EventType]
public record DecSimpleUserCreated(string Name, string Email, DateTimeOffset CreatedAt);

View C# snippet source on GitHub

Kotlin

import io.cratis.chronicle.events.EventType
import java.time.OffsetDateTime

@EventType
data class DecSimpleUserCreated(val name: String, val email: String, val createdAt: OffsetDateTime)

View Kotlin snippet source on GitHub

Java

import io.cratis.chronicle.events.EventType;

@EventType
record DecSimpleUserCreated(String name, String email, String createdAt) {}

View Java snippet source on GitHub

Elixir

defmodule MyApp.Events.DecSimpleUserCreated do
  use Chronicle.Events.EventType, id: "dec-simple-user-created"

  defstruct [:name, :email, :created_at]
end

View Elixir snippet source on GitHub

TypeScript

class DecSimpleUserCreated {
    name = '';
    email = '';
    createdAt = new Date();
}

View TypeScript snippet source on GitHub

How it works

When a UserCreated event is appended to the event log:

1. The projection automatically creates or updates a User read model
2. The event source ID becomes the key for the read model
3. Properties with matching names are copied from event to read model
4. The read model is stored and can be queried

Auto-mapping works when property names and types match between the event and read model. For more control over the mapping, see projection with custom properties.