Projection with joins

Joins allow projections to incorporate data from events that don’t share the same event source ID. This enables building read models that combine data from different streams.

Defining a projection with joins

Use the Join() method to include data from events with different keys:

C#

using Cratis.Chronicle.Projections;

public class DecJoinsUserProjection : IProjectionFor<DecJoinsUser>
{
    public void Define(IProjectionBuilderFor<DecJoinsUser> builder) => builder
        .From<DecJoinsUserCreated>()
        .From<DecJoinsUserAssignedToGroup>(b => b
            .UsingKey(e => e.UserId)
            .Set(m => m.GroupId).ToEventSourceId())
        .Join<DecJoinsGroupCreated>(j => j
            .On(m => m.GroupId))
        .Join<DecJoinsGroupRenamed>(j => j
            .On(m => m.GroupId));
}

View C# snippet source on GitHub

Kotlin

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

class DecJoinsUserProjection : IProjectionFor<DecJoinsUser> {
    override fun define(builder: IProjectionBuilderFor<DecJoinsUser>) {
        builder
            .from(DecJoinsUserCreated::class)
            .from(DecJoinsUserAssignedToGroup::class) {
                it.usingKey("userId")
                it.set(DecJoinsUser::groupId).toEventSourceId()
            }
            .join(DecJoinsGroupCreated::class) { it.on(DecJoinsUser::groupId) }
            .join(DecJoinsGroupRenamed::class) { it.on(DecJoinsUser::groupId) }
    }
}

View Kotlin snippet source on GitHub

Java

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

class DecJoinsUserProjection implements IProjectionFor<DecJoinsUser> {
    @Override
    public void define(IProjectionBuilderFor<DecJoinsUser> builder) {
        builder
            .from(DecJoinsUserCreated.class)
            .from(DecJoinsUserAssignedToGroup.class, fb -> {
                fb.usingKey("userId");
                fb.set("groupId").toEventSourceId();
            })
            .join(DecJoinsGroupCreated.class, jb -> {
                jb.on("groupId");
            })
            .join(DecJoinsGroupRenamed.class, jb -> {
                jb.on("groupId");
            });
    }
}

View Java snippet source on GitHub

Elixir

defmodule MyApp.Projections.DecJoinsUserProjection do
  use Chronicle.Projections.Projection, model: MyApp.ReadModels.DecJoinsUser

  alias MyApp.Events.{
    DecJoinsUserCreated,
    DecJoinsUserAssignedToGroup,
    DecJoinsGroupCreated,
    DecJoinsGroupRenamed
  }

  from DecJoinsUserCreated

  from DecJoinsUserAssignedToGroup,
    key: :user_id,
    set: [group_id: :event_source_id]

  join DecJoinsGroupCreated, on: :group_id
  join DecJoinsGroupRenamed, on: :group_id
end

View Elixir snippet source on GitHub

TypeScript

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

@projection()
class DecJoinsUserProjection implements IProjectionFor<DecJoinsUser> {
    define(builder: IProjectionBuilderFor<DecJoinsUser>): void {
        builder
            .autoMap()
            .from(DecJoinsUserCreated)
            .from(DecJoinsUserAssignedToGroup, b => b
                .usingKey(e => e.userId)
                .set(m => m.groupId).toEventSourceId())
            .join(DecJoinsGroupCreated, j => j
                .on(m => m.groupId))
            .join(DecJoinsGroupRenamed, j => j
                .on(m => m.groupId));
    }
}

View TypeScript snippet source on GitHub

Read model with joined data

The read model includes properties populated from different event sources:

C#

public record DecJoinsUser(
    string Name,
    string Email,
    string? GroupId,
    string? GroupName,
    string? GroupDescription);

View C# snippet source on GitHub

Kotlin

data class DecJoinsUser(
    val name: String = "",
    val email: String = "",
    val groupId: String? = null,
    val groupName: String? = null,
    val groupDescription: String? = null
)

View Kotlin snippet source on GitHub

Java

class DecJoinsUser {
    public String name = "";
    public String email = "";
    public String groupId = null;
    public String groupName = null;
    public String groupDescription = null;
}

View Java snippet source on GitHub

Elixir

Read model

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

  defstruct [:name, :email, :group_id, :group_name, :group_description]
end

View Elixir snippet source on GitHub

TypeScript

class DecJoinsUser {
    name = '';
    email = '';
    groupId: string | null = null;
    groupName: string | null = null;
    groupDescription: string | null = null;
}

View TypeScript snippet source on GitHub

Event definitions

Events come from different streams but are joined based on common identifiers:

C#

using Cratis.Chronicle.Events;

// User stream events
[EventType]
public record DecJoinsUserCreated(string Name, string Email);

[EventType]
public record DecJoinsUserAssignedToGroup(string UserId, string GroupId);

// Group stream events
[EventType]
public record DecJoinsGroupCreated(string Name, string Description);

[EventType]
public record DecJoinsGroupRenamed(string NewName);

View C# snippet source on GitHub

Kotlin

import io.cratis.chronicle.events.EventType

// User stream events
@EventType
data class DecJoinsUserCreated(val name: String, val email: String)

@EventType
data class DecJoinsUserAssignedToGroup(val userId: String, val groupId: String)

// Group stream events
@EventType
data class DecJoinsGroupCreated(val name: String, val description: String)

@EventType
data class DecJoinsGroupRenamed(val newName: String)

View Kotlin snippet source on GitHub

Java

import io.cratis.chronicle.events.EventType;

// User stream events
@EventType
record DecJoinsUserCreated(String name, String email) {}

@EventType
record DecJoinsUserAssignedToGroup(String userId, String groupId) {}

// Group stream events
@EventType
record DecJoinsGroupCreated(String name, String description) {}

@EventType
record DecJoinsGroupRenamed(String newName) {}

View Java snippet source on GitHub

Elixir

Events

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

  defstruct [:name, :email]
end

defmodule MyApp.Events.DecJoinsUserAssignedToGroup do
  use Chronicle.Events.EventType, id: "dec-joins-user-assigned-to-group"

  defstruct [:user_id, :group_id]
end

defmodule MyApp.Events.DecJoinsGroupCreated do
  use Chronicle.Events.EventType, id: "dec-joins-group-created"

  defstruct [:name, :description]
end

defmodule MyApp.Events.DecJoinsGroupRenamed do
  use Chronicle.Events.EventType, id: "dec-joins-group-renamed"

  defstruct [:new_name]
end

View Elixir snippet source on GitHub

TypeScript

import { eventType } from '@cratis/chronicle';
import { field } from '@cratis/fundamentals';

// User stream events
@eventType()
class DecJoinsUserCreated {
    @field(String) readonly name: string;
    @field(String) readonly email: string;

    constructor(name: string, email: string) {
        this.name = name;
        this.email = email;
    }
}

@eventType()
class DecJoinsUserAssignedToGroup {
    @field(String) readonly userId: string;
    @field(String) readonly groupId: string;

    constructor(userId: string, groupId: string) {
        this.userId = userId;
        this.groupId = groupId;
    }
}

// Group stream events
@eventType()
class DecJoinsGroupCreated {
    @field(String) readonly name: string;
    @field(String) readonly description: string;

    constructor(name: string, description: string) {
        this.name = name;
        this.description = description;
    }
}

@eventType()
class DecJoinsGroupRenamed {
    @field(String) readonly newName: string;

    constructor(newName: string) {
        this.newName = newName;
    }
}

View TypeScript snippet source on GitHub

How joins work

1. Primary events establish the read model and may set join keys
2. Join conditions specify which property links to other streams
3. Joined events update properties when their event source ID matches the join key
4. Join properties are updated whenever relevant events occur
5. Joined values take precedence — a joined property is applied over any value a From block wrote for the same property, in whichever order the events arrived

Join scenarios

Setting join keys

Join keys are typically set from events that establish relationships — in the example above, UserAssignedToGroup sets GroupId to the group’s own event source ID via .ToEventSourceId().

Joining on the key

Joins match events based on their event source ID and the join property — .Join<GroupCreated>(j => j.On(m => m.GroupId)) links in group data whenever a GroupCreated/GroupRenamed event’s event source ID matches the read model’s GroupId.

Join precedence

When a From block and a join write the same property, the joined value wins — regardless of arrival order. Whenever the projection handles a From event, Chronicle re-resolves the join against the joined stream’s last stored event and applies the joined properties after the From mappings. A From block therefore cannot reset or clear a property a join has written; there is no “clear this joined value” operation. If a property must reflect which fact happened most recently, give each fact its own property (for example, two timestamps) and compare them, rather than latching a single flag written from both sides. The CHR0042 analyzer warns when the same property is written from both sides.

Multiple joins

A projection can join with multiple streams:

C#

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Projections;

[EventType]
public record DecJoinsMultipleEmployeeAssigned(string GroupId, string DepartmentId, string LocationId);

[EventType]
public record DecJoinsMultipleGroupCreated(string Name);

[EventType]
public record DecJoinsMultipleDepartmentCreated(string Name);

[EventType]
public record DecJoinsMultipleLocationUpdated(string Address);

public record DecJoinsMultipleEmployeeSummary(
    string? GroupId,
    string? GroupName,
    string? DepartmentId,
    string? DepartmentName,
    string? LocationId,
    string? LocationAddress);

public class DecJoinsMultipleEmployeeSummaryProjection : IProjectionFor<DecJoinsMultipleEmployeeSummary>
{
    public void Define(IProjectionBuilderFor<DecJoinsMultipleEmployeeSummary> builder) => builder
        .From<DecJoinsMultipleEmployeeAssigned>()
        .Join<DecJoinsMultipleGroupCreated>(j => j.On(m => m.GroupId))
        .Join<DecJoinsMultipleDepartmentCreated>(j => j.On(m => m.DepartmentId))
        .Join<DecJoinsMultipleLocationUpdated>(j => j.On(m => m.LocationId));
}

View C# snippet source on GitHub

Kotlin

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

@EventType
data class DecJoinsMultipleEmployeeAssigned(val groupId: String, val departmentId: String, val locationId: String)

@EventType
data class DecJoinsMultipleGroupCreated(val name: String)

@EventType
data class DecJoinsMultipleDepartmentCreated(val name: String)

@EventType
data class DecJoinsMultipleLocationUpdated(val address: String)

data class DecJoinsMultipleEmployeeSummary(
    val groupId: String? = null,
    val groupName: String? = null,
    val departmentId: String? = null,
    val departmentName: String? = null,
    val locationId: String? = null,
    val locationAddress: String? = null
)

class DecJoinsMultipleEmployeeSummaryProjection : IProjectionFor<DecJoinsMultipleEmployeeSummary> {
    override fun define(builder: IProjectionBuilderFor<DecJoinsMultipleEmployeeSummary>) {
        builder
            .from(DecJoinsMultipleEmployeeAssigned::class)
            .join(DecJoinsMultipleGroupCreated::class) { it.on(DecJoinsMultipleEmployeeSummary::groupId) }
            .join(DecJoinsMultipleDepartmentCreated::class) { it.on(DecJoinsMultipleEmployeeSummary::departmentId) }
            .join(DecJoinsMultipleLocationUpdated::class) { it.on(DecJoinsMultipleEmployeeSummary::locationId) }
    }
}

View Kotlin snippet source on GitHub

Java

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

@EventType
record DecJoinsMultipleEmployeeAssigned(String groupId, String departmentId, String locationId) {}

@EventType
record DecJoinsMultipleGroupCreated(String name) {}

@EventType
record DecJoinsMultipleDepartmentCreated(String name) {}

@EventType
record DecJoinsMultipleLocationUpdated(String address) {}

class DecJoinsMultipleEmployeeSummary {
    public String groupId = null;
    public String groupName = null;
    public String departmentId = null;
    public String departmentName = null;
    public String locationId = null;
    public String locationAddress = null;
}

class DecJoinsMultipleEmployeeSummaryProjection implements IProjectionFor<DecJoinsMultipleEmployeeSummary> {
    @Override
    public void define(IProjectionBuilderFor<DecJoinsMultipleEmployeeSummary> builder) {
        builder
            .from(DecJoinsMultipleEmployeeAssigned.class)
            .join(DecJoinsMultipleGroupCreated.class, jb -> {
                jb.on("groupId");
            })
            .join(DecJoinsMultipleDepartmentCreated.class, jb -> {
                jb.on("departmentId");
            })
            .join(DecJoinsMultipleLocationUpdated.class, jb -> {
                jb.on("locationId");
            });
    }
}

View Java snippet source on GitHub

Elixir

Multiple joins

defmodule MyApp.Events.DecJoinsMultipleEmployeeAssigned do
  use Chronicle.Events.EventType, id: "dec-joins-multiple-employee-assigned"

  defstruct [:group_id, :department_id, :location_id]
end

defmodule MyApp.Events.DecJoinsMultipleGroupCreated do
  use Chronicle.Events.EventType, id: "dec-joins-multiple-group-created"

  defstruct [:name]
end

defmodule MyApp.Events.DecJoinsMultipleDepartmentCreated do
  use Chronicle.Events.EventType, id: "dec-joins-multiple-department-created"

  defstruct [:name]
end

defmodule MyApp.Events.DecJoinsMultipleLocationUpdated do
  use Chronicle.Events.EventType, id: "dec-joins-multiple-location-updated"

  defstruct [:address]
end

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

  defstruct [:group_id, :group_name, :department_id, :department_name, :location_id, :location_address]
end

defmodule MyApp.Projections.DecJoinsMultipleEmployeeSummaryProjection do
  use Chronicle.Projections.Projection, model: MyApp.ReadModels.DecJoinsMultipleEmployeeSummary

  alias MyApp.Events.{
    DecJoinsMultipleEmployeeAssigned,
    DecJoinsMultipleGroupCreated,
    DecJoinsMultipleDepartmentCreated,
    DecJoinsMultipleLocationUpdated
  }

  from DecJoinsMultipleEmployeeAssigned

  join DecJoinsMultipleGroupCreated, on: :group_id
  join DecJoinsMultipleDepartmentCreated, on: :department_id
  join DecJoinsMultipleLocationUpdated, on: :location_id
end

View Elixir snippet source on GitHub

TypeScript

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

@eventType()
class DecJoinsMultipleEmployeeAssigned {
    groupId = '';
    departmentId = '';
    locationId = '';
}

@eventType()
class DecJoinsMultipleGroupCreated {
    name = '';
}

@eventType()
class DecJoinsMultipleDepartmentCreated {
    name = '';
}

@eventType()
class DecJoinsMultipleLocationUpdated {
    address = '';
}

class DecJoinsMultipleEmployeeSummary {
    groupId: string | null = null;
    groupName: string | null = null;
    departmentId: string | null = null;
    departmentName: string | null = null;
    locationId: string | null = null;
    locationAddress: string | null = null;
}

@projection()
class DecJoinsMultipleEmployeeSummaryProjection implements IProjectionFor<DecJoinsMultipleEmployeeSummary> {
    define(builder: IProjectionBuilderFor<DecJoinsMultipleEmployeeSummary>): void {
        builder
            .autoMap()
            .from(DecJoinsMultipleEmployeeAssigned)
            .join(DecJoinsMultipleGroupCreated, j => j.on(m => m.groupId))
            .join(DecJoinsMultipleDepartmentCreated, j => j.on(m => m.departmentId))
            .join(DecJoinsMultipleLocationUpdated, j => j.on(m => m.locationId));
    }
}

View TypeScript snippet source on GitHub

Joining children

Joins can also be used within child collections. Inside Children a join always matches the joined event’s event source against the child’s identity (IdentifiedBy), so .On() is not used there. Identify the children by the id of the stream you join; here each member on a project board gets its name from the member’s own MemberRegistered event:

C#

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Projections;

[EventType]
public record DecJoinsChildMemberAssignedToProject(string ProjectId, string MemberId);

[EventType]
public record DecJoinsChildMemberRegistered(string Name);

public record DecJoinsChildProjectMember(string MemberId, string? Name);

public record DecJoinsChildProjectBoard(IEnumerable<DecJoinsChildProjectMember> Members);

public class DecJoinsChildProjectBoardProjection : IProjectionFor<DecJoinsChildProjectBoard>
{
    public void Define(IProjectionBuilderFor<DecJoinsChildProjectBoard> builder) => builder
        .Children(m => m.Members, children => children
            .IdentifiedBy(e => e.MemberId)
            .From<DecJoinsChildMemberAssignedToProject>(b => b
                .UsingParentKey(e => e.ProjectId)
                .UsingKey(e => e.MemberId))
            .Join<DecJoinsChildMemberRegistered>());
}

View C# snippet source on GitHub

Kotlin

Kotlin does not support this workflow yet.
`IChildrenBuilderFor` has no `join()` method — joins are only available on the top-level
`IProjectionBuilderFor<TReadModel>`, not inside a child collection scope.

View Kotlin snippet source on GitHub

Java

Java does not support this workflow yet.
`IChildrenBuilderFor` has no `join()` method — joins are only available on the top-level
`IProjectionBuilderFor<TReadModel>`, not inside a child collection scope.

View Java snippet source on GitHub

Elixir

defmodule MyApp.Events.DecJoinsChildMemberAssignedToProject do
  use Chronicle.Events.EventType, id: "dec-joins-child-member-assigned-to-project"

  defstruct [:project_id, :member_id]
end

defmodule MyApp.Events.DecJoinsChildMemberRegistered do
  use Chronicle.Events.EventType, id: "dec-joins-child-member-registered"

  defstruct [:name]
end

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

  defstruct member_id: nil, name: nil
end

defmodule MyApp.ReadModels.DecJoinsChildProjectBoard do
  use Chronicle.ReadModels.ReadModel,
    types: [members: {:list, MyApp.ReadModels.DecJoinsChildProjectMember}]

  defstruct members: []
end

defmodule MyApp.Projections.DecJoinsChildProjectBoardProjection do
  use Chronicle.Projections.Projection, model: MyApp.ReadModels.DecJoinsChildProjectBoard

  children :members, identified_by: :member_id do
    from MyApp.Events.DecJoinsChildMemberAssignedToProject,
      parent_key: :project_id,
      key: :member_id,
      set: [member_id: :member_id]

    join MyApp.Events.DecJoinsChildMemberRegistered,
      on: :member_id,
      set: [name: :name]
  end
end

View Elixir snippet source on GitHub

TypeScript

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

@eventType()
class DecJoinsChildTaskAssigned {
    @field(String) readonly taskId: string;
    @field(String) readonly projectId: string;

    constructor(taskId: string, projectId: string) {
        this.taskId = taskId;
        this.projectId = projectId;
    }
}

@eventType()
class DecJoinsChildProjectCreated {
    @field(String) readonly name: string;

    constructor(name: string) {
        this.name = name;
    }
}

class DecJoinsChildTask {
    taskId = '';
    projectId = '';
    projectName: string | null = null;
}

class DecJoinsChildProjectBoard {
    tasks: DecJoinsChildTask[] = [];
}

@projection()
class DecJoinsChildProjectBoardProjection implements IProjectionFor<DecJoinsChildProjectBoard> {
    define(builder: IProjectionBuilderFor<DecJoinsChildProjectBoard>): void {
        builder
            .children<DecJoinsChildTask>(m => m.tasks, children => children
                .identifiedBy(e => e.taskId)
                .autoMap()
                .from(DecJoinsChildTaskAssigned, b => b
                    .usingKey(e => e.taskId))
                .join(DecJoinsChildProjectCreated, j => j
                    .on(m => m.projectId)));
    }
}

View TypeScript snippet source on GitHub

Automatic mapping in declaration-language joins

A with <Event> block inherits the projection’s automap setting by default. Use no automap inside that with block to map only properties you declare explicitly, even when the joined event and read model have same-named properties. Use automap there to enable matching by name even if the enclosing projection disables it. This setting also applies when Chronicle backfills joined values from earlier events. Per-join automap and no automap are declaration-language only: the .NET JoinBuilder and the C#, Kotlin, and TypeScript code generators do not express them. Code generated from a declaration with a per-join override will not preserve that override; keep the declaration as the source of truth.

Performance considerations

• Joins require Chronicle to track relationships between streams
• The system automatically manages join indexes and updates
• Consider the frequency of joined events when designing projections
• Large numbers of joins may impact projection performance

Joins enable powerful cross-stream read models while maintaining the benefits of event sourcing and proper stream boundaries.