Skip to content

Appended event metadata and projections

Chronicle projections consume every event of the types declared in their mappings, regardless of append metadata. To build a view or trigger an effect from only tagged events, use a reducer or reactor alongside the projection. [FilterEventsByTag], [EventSourceType], and [EventStreamType] do not narrow a projection’s input.

Choose the input event types in the mapping definition. This order summary maps placement and shipping events:

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Keys;
using Cratis.Chronicle.Projections.ModelBound;
[EventType]
public record FilteringOrderPlaced(string CustomerId, decimal TotalAmount);
[EventType]
public record FilteringOrderShipped(DateTimeOffset ShippedAt);
[FromEvent<FilteringOrderPlaced>]
[FromEvent<FilteringOrderShipped>]
public record FilteringOrderSummary(
[Key] string CustomerId,
decimal TotalAmount,
DateTimeOffset? ShippedAt);

View C# snippet source on GitHub

The projection receives every event of those declared types. Adding a tag or stream type when appending an order does not change whether the projection sees it.

Changing the mapped event types changes the state that can be built from history. Review definition evolution before deploying that change: newly selected event types with existing history require a rebuild.

[Tag] and [Tags] on a projection label the projection definition for organizational purposes. They do not filter incoming events:

using Cratis.Chronicle;
using Cratis.Chronicle.Projections;
public record FilteringOrderReport(string CustomerId);
// Labels the projection for discoverability — does not affect which events are received
[Tag("reporting")]
public class FilteringOrderReportingProjection : IProjectionFor<FilteringOrderReport>
{
public void Define(IProjectionBuilderFor<FilteringOrderReport> builder) =>
builder.From<FilteringOrderPlaced>(b => b.UsingKey(e => e.CustomerId));
}

View C# snippet source on GitHub

Combining a projection with metadata-based filtering

Section titled “Combining a projection with metadata-based filtering”

Keep the complete order summary in the projection, and give the subset its own consumer. Use a reactor for a side effect and a reducer for a separate stateful read model.

In this example, the projection builds summaries for all orders. The accompanying reactor handles only orders appended with the premium tag:

using Cratis.Chronicle;
using Cratis.Chronicle.Events;
using Cratis.Chronicle.Keys;
using Cratis.Chronicle.Projections.ModelBound;
using Cratis.Chronicle.Reactors;
[EventType]
public record FilteringWithReactorOrderPlaced(string CustomerId, decimal TotalAmount);
// --- Append call ---
// Carries the "premium" tag for orders that qualify
// eventLog.Append(orderId, new FilteringWithReactorOrderPlaced(customerId, total), tags: ["premium"]);
// --- Projection: receives every OrderPlaced ---
[FromEvent<FilteringWithReactorOrderPlaced>]
public record FilteringWithReactorOrderSummary(
[Key] string CustomerId,
decimal TotalAmount);
// --- Reactor: receives only premium-tagged OrderPlaced ---
[FilterEventsByTag("premium")]
public class FilteringWithReactorPremiumOrderNotifier : IReactor
{
public Task Placed(FilteringWithReactorOrderPlaced @event, EventContext context) =>
Task.CompletedTask;
}

View C# snippet source on GitHub

For premium-order totals, the reducer’s [FilterEventsByTag("premium")] selects that subset before its code updates the count and total:

using Cratis.Chronicle;
using Cratis.Chronicle.Events;
using Cratis.Chronicle.Reducers;
public record FilteringPremiumOrderTotals(int Count, decimal Total);
[FilterEventsByTag("premium")]
public class FilteringPremiumOrderTotalsReducer : IReducerFor<FilteringPremiumOrderTotals>
{
public FilteringPremiumOrderTotals Placed(FilteringWithReactorOrderPlaced @event, FilteringPremiumOrderTotals? current, EventContext context) =>
new((current?.Count ?? 0) + 1, (current?.Total ?? 0m) + @event.TotalAmount);
}

View C# snippet source on GitHub

If a screen only needs to hide some existing order summaries, filter the query result instead. You do not need a second consumer when the underlying state should remain the same.

Supply the metadata when appending the event so the reducer or reactor can match it. In this example, the premium tag selects the filtered consumer without changing the projection’s behavior:

using Cratis.Chronicle.Events;
using Cratis.Chronicle.EventSequences;
public class FilteringAppendService(IEventLog eventLog)
{
public async Task AppendOrders(string customerId)
{
// Appends to all observers — no extra metadata
await eventLog.Append(EventSourceId.New(), new FilteringWithReactorOrderPlaced(customerId, 42m));
// Appends to all observers; additionally dispatched to observers filtering on "premium"
await eventLog.Append(EventSourceId.New(), new FilteringWithReactorOrderPlaced(customerId, 299m), tags: ["premium"]);
// Appends with stream type; dispatched to observers filtering on "wholesale" stream type
await eventLog.Append(EventSourceId.New(), new FilteringWithReactorOrderPlaced(customerId, 1500m), eventStreamType: "wholesale");
}
}

View C# snippet source on GitHub