---
title: 'Cratis Chronicle projections: dictionary keys'
editUrl: https://github.com/Cratis/Chronicle/edit/main/Documentation/projections/declarative/dictionaries.mdx
description: Key a Cratis Chronicle read model dictionary by event content, event context or the causing identity, and remove dictionary keys when an event says so.
lastUpdated: 2026-11-09T00:00:00.000Z
---

A dictionary property in a Cratis Chronicle read model can hold one entry per key, where the key is resolved for each event. Use it when a read model needs a value per slot, per category or per user, and the set of keys is only known from the events themselves.

## Where the key comes from

The key of each entry is read from the event that is being projected:

| Key source | Example key |
| --- | --- |
| Event content | A property on the event, such as the slot a series was assigned to. Nested event properties work too. |
| Event context | Metadata accompanying the event, such as the event type identifier. |
| Caused by | The subject, name or user name of the identity that caused the event. |

Keys are strings. A key value that is a strongly typed concept is stored by its underlying value. Values are turned into keys the same way on every server, regardless of its culture, with numbers in the invariant format. Dates and times read from event content use ISO 8601 with a comma before the fraction of a second, for example `2026-03-04T05:06:07,0000000+02:00`. Dates read from the event context, such as when the event occurred, keep their general invariant format, for example `03/04/2026 05:06:07 +02:00`.

A key read from event content cannot be empty, cannot contain `.`, `[`, `]` or a null character, and cannot start with `$`, because the storage cannot address a property by such a key. A key is never escaped silently: an event that resolves such a key fails, and the failure shows on its partition in the Workbench. Choose a key source that cannot hold these characters, such as an identifier, rather than free text or a number with decimals.

A key read from the event context or the causing identity is not checked. A `.` in such a key, for example in a user name such as `john.doe`, nests the value one level deeper instead of making a single entry. Prefer the subject, which is an identifier, when keying by the causing identity.

When the key is read from event content, the event property must exist on the event type. A key path the event type does not have fails when the projection is registered.

When the key's source is missing or null on a particular event, the mapping is skipped for that event. Nothing is written, and no entry with an empty key is created.

The dictionary property must be a dictionary on the read model, or an object without properties of its own. Using a dynamic key on a property with a fixed shape fails when the projection is registered.

In the next example the slot on each event picks the entry. Assigning a series to a slot that already has one replaces it, and clearing a slot removes its entry:

**C#**

```csharp
using Cratis.Chronicle.Events;
using Cratis.Chronicle.Projections;

[EventType]
public record DecDictionarySeriesAssigned(string Slot, string SeriesId);

[EventType]
public record DecDictionarySlotCleared(string Slot);

public record DecDictionarySchedule(IDictionary<string, string> SeriesBySlot);

public class DecDictionaryScheduleProjection : IProjectionFor<DecDictionarySchedule>
{
    public void Define(IProjectionBuilderFor<DecDictionarySchedule> builder) => builder
        .From<DecDictionarySeriesAssigned>(_ => _
            .Set(m => m.SeriesBySlot, e => e.Slot).To(e => e.SeriesId))
        .From<DecDictionarySlotCleared>(_ => _
            .RemoveKey(m => m.SeriesBySlot, e => e.Slot));
}
```

[View C# snippet source on GitHub](https://github.com/Cratis/Chronicle/blob/main/Documentation/client-snippets/projections/declarative/dictionaries/keyed-by-event-content.md)

**Elixir**

```elixir title="Dictionary entries keyed by event content"
defmodule MyApp.Events.DecDictionarySeriesAssigned do
  use Chronicle.Events.EventType, id: "dec-dictionary-series-assigned"

  defstruct slot: "", series_id: ""
end

defmodule MyApp.Events.DecDictionarySlotCleared do
  use Chronicle.Events.EventType, id: "dec-dictionary-slot-cleared"

  defstruct slot: ""
end

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

  defstruct series_by_slot: %{}
end

defmodule MyApp.Projections.DecDictionaryScheduleProjection do
  use Chronicle.Projections.Projection, model: MyApp.ReadModels.DecDictionarySchedule

  alias MyApp.Events.{DecDictionarySeriesAssigned, DecDictionarySlotCleared}

  from DecDictionarySeriesAssigned,
    set: [series_by_slot: {:entry, {:event_content, :slot}, :series_id}]

  from DecDictionarySlotCleared,
    remove: [series_by_slot: {:event_content, :slot}]
end
```

[View Elixir snippet source on GitHub](https://github.com/Cratis/Chronicle.Elixir/blob/main/Documentation/client-snippets/projections/declarative/dictionaries/keyed-by-event-content.md)

**TypeScript**

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

@eventType()
class DecDictionarySeriesAssigned {
    slot = '';
    seriesId = '';
}

@eventType()
class DecDictionarySlotCleared {
    slot = '';
}

class DecDictionarySchedule {
    seriesBySlot: Record<string, string> = {};
}

@projection()
class DecDictionaryScheduleProjection implements IProjectionFor<DecDictionarySchedule> {
    define(builder: IProjectionBuilderFor<DecDictionarySchedule>): void {
        builder
            .from(DecDictionarySeriesAssigned, _ => _
                .set(m => m.seriesBySlot, e => e.slot).to(e => e.seriesId))
            .from(DecDictionarySlotCleared, _ => _
                .removeKey(m => m.seriesBySlot, e => e.slot));
    }
}
```

[View TypeScript snippet source on GitHub](https://github.com/Cratis/Chronicle.TypeScript/blob/main/Documentation/client-snippets/projections/declarative/dictionaries/keyed-by-event-content.md)

## Operations on a dictionary entry

Every property operation works on the entry the key selects:

| Operation | Effect on the entry |
| --- | --- |
| Set | Assigns a value, overwriting what the key held before. |
| Set once | Assigns a value only when the key is missing or holds null. See [setting a value only once](/chronicle/projections/declarative/set-properties/#setting-a-value-only-once). |
| Add and subtract | Adds an event value to, or subtracts it from, the entry. |
| Increment, decrement and count | Changes the entry by one. |
| Remove | Removes the key from the dictionary. |

Set and set once follow the dictionary's declared value type; when the dictionary declares none, they store the event value as it is. Add, subtract, increment, decrement and count always use 64-bit integers, whatever value type the dictionary declares.

The next example keeps the units sold and a sales count per category from the event, counts sales per user from the identity that caused each event, and records when each category sold first:

**C#**

```csharp
using Cratis.Chronicle.Events;
using Cratis.Chronicle.Projections;

[EventType]
public record DecDictionaryItemSold(string Category, int Quantity);

[EventType]
public record DecDictionaryItemReturned(string Category, int Quantity);

public record DecDictionarySales(
    IDictionary<string, long> UnitsByCategory,
    IDictionary<string, int> SalesByCategory,
    IDictionary<string, int> SalesByUser,
    IDictionary<string, DateTimeOffset> FirstSaleByCategory);

public class DecDictionarySalesProjection : IProjectionFor<DecDictionarySales>
{
    public void Define(IProjectionBuilderFor<DecDictionarySales> builder) => builder
        .From<DecDictionaryItemSold>(_ => _
            .Add(m => m.UnitsByCategory, e => e.Category).With(e => e.Quantity)
            .Increment(m => m.SalesByCategory, e => e.Category)
            .Count(m => m.SalesByUser, c => c.CausedBy.Subject)
            .SetOnce(m => m.FirstSaleByCategory, e => e.Category).ToEventContextProperty(c => c.Occurred))
        .From<DecDictionaryItemReturned>(_ => _
            .Subtract(m => m.UnitsByCategory, e => e.Category).With(e => e.Quantity)
            .Decrement(m => m.SalesByCategory, e => e.Category));
}
```

[View C# snippet source on GitHub](https://github.com/Cratis/Chronicle/blob/main/Documentation/client-snippets/projections/declarative/dictionaries/operations.md)

**Elixir**

```elixir title="Dictionary operations keyed per event"
defmodule MyApp.Events.DecDictionaryItemSold do
  use Chronicle.Events.EventType, id: "dec-dictionary-item-sold"

  defstruct category: "", quantity: 0
end

defmodule MyApp.Events.DecDictionaryItemReturned do
  use Chronicle.Events.EventType, id: "dec-dictionary-item-returned"

  defstruct category: "", quantity: 0
end

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

  defstruct units_by_category: %{},
            sales_by_category: %{},
            sales_by_user: %{},
            first_sale_by_category: %{}
end

defmodule MyApp.Projections.DecDictionarySalesProjection do
  use Chronicle.Projections.Projection, model: MyApp.ReadModels.DecDictionarySales

  alias MyApp.Events.{DecDictionaryItemReturned, DecDictionaryItemSold}

  from DecDictionaryItemSold,
    add: [units_by_category: {:entry, {:event_content, :category}, :quantity}],
    increment: [sales_by_category: {:event_content, :category}],
    count: [sales_by_user: {:caused_by, :subject}],
    set_once: [first_sale_by_category: {:entry, {:event_content, :category}, :occurred}]

  from DecDictionaryItemReturned,
    subtract: [units_by_category: {:entry, {:event_content, :category}, :quantity}],
    decrement: [sales_by_category: {:event_content, :category}]
end
```

[View Elixir snippet source on GitHub](https://github.com/Cratis/Chronicle.Elixir/blob/main/Documentation/client-snippets/projections/declarative/dictionaries/operations.md)

**TypeScript**

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

@eventType()
class DecDictionaryItemSold {
    category = '';
    quantity = 0;
}

@eventType()
class DecDictionaryItemReturned {
    category = '';
    quantity = 0;
}

class DecDictionarySales {
    unitsByCategory: Record<string, number> = {};
    salesByCategory: Record<string, number> = {};
    salesByUser: Record<string, number> = {};
    firstSaleByCategory: Record<string, Date> = {};
}

@projection()
class DecDictionarySalesProjection implements IProjectionFor<DecDictionarySales> {
    define(builder: IProjectionBuilderFor<DecDictionarySales>): void {
        builder
            .from(DecDictionaryItemSold, _ => _
                .add(m => m.unitsByCategory, e => e.category).with(e => e.quantity)
                .increment(m => m.salesByCategory, e => e.category)
                .count(m => m.salesByUser, DictionaryKey.causedBy('subject'))
                .setOnce(m => m.firstSaleByCategory, e => e.category).toEventContextProperty('occurred'))
            .from(DecDictionaryItemReturned, _ => _
                .subtract(m => m.unitsByCategory, e => e.category).with(e => e.quantity)
                .decrement(m => m.salesByCategory, e => e.category));
    }
}
```

[View TypeScript snippet source on GitHub](https://github.com/Cratis/Chronicle.TypeScript/blob/main/Documentation/client-snippets/projections/declarative/dictionaries/operations.md)

## Removing a key

A remove mapping takes the key out of the dictionary entirely - the entry is gone, it is not left holding null. Removing a key that is not present does nothing. Every sink removes the key the same way, so a read model looks the same whether it is stored in MongoDB, a SQL database or in memory.

A remove mapping must address a dictionary entry through a dynamic key. Removing a property without one fails when the projection is registered; to clear a regular property, set it to null instead.

## Related topics

- [Set properties](/chronicle/projections/declarative/set-properties/) for mapping regular properties.
- [FromAll](/chronicle/projections/declarative/from-all/) for counting every event type into a dictionary.
- [Event context](/chronicle/projections/declarative/event-context/) for the metadata that can serve as a key.
