Skip to content

Cratis Chronicle event reads for inspecting history

Read events directly from Cratis Chronicle when you need to inspect an entity’s history or diagnose the facts behind its current state. Use an event source read for one entity, a sequence-number read for a known position, or a metadata lookup when you do not need the payload.

The .NET examples use IEventSequence and its specialized IEventLog. For a history view that should not load everything at once, use .NET keyset-paged reads: pages advance by sequence number rather than by an offset. GetPage reads forward or backward within inclusive bounds; GetLatest starts at the tail and returns matching events newest first. Both return a continuation only when another matching page exists.

Use GetMetadataAt when you already know an event’s sequence number and need its context, not its payload. The single-locator overload returns null for a missing event. The batch overload returns an immutable dictionary keyed by sequence number and omits missing events.

using Cratis.Chronicle.Events;
using Cratis.Chronicle.EventSequences;
public static class EventMetadataReads
{
// Call only after your application authorizes access to these events.
public static async Task Read(IEventSequence eventSequence)
{
EventMetadata? metadata = await eventSequence.GetMetadataAt((EventSequenceNumber)42UL);
if (metadata is not null)
{
Console.WriteLine($"{metadata.EventStreamType}: {metadata.CausedBy.Resolution}");
}
var batch = await eventSequence.GetMetadataAt([42UL, 43UL]);
foreach (var entry in batch.Values)
{
Console.WriteLine($"{entry.SequenceNumber}: {entry.CausedBy.Name ?? "Name unavailable"}");
}
}
}

View C# snippet source on GitHub

A request accepts at most 500 locators, including duplicates. Chronicle rejects larger requests before querying storage and removes duplicates from accepted requests. These are point lookups, not reads of everything after a checkpoint.

Metadata includes routing, occurred time, correlation, causation, tags, subject, source name, and the caused-by identity chain. It contains no payload, generation, content hash or revision content, and does not release compliance-protected data. Identity names resolve from storage on each read, so a rename appears on the next metadata read. See identity resolution for the resolution statuses and privacy boundaries.

Your application must authorize access to the event store, namespace and requested events before calling this API. Metadata can still contain personal information, including identity names, tags and causation properties.

using Cratis.Chronicle.Events;
using Cratis.Chronicle.EventSequences;
using System.Collections.Immutable;
[EventType]
public record GettingEventsOrderPlaced(string OrderId, decimal Total);
[EventType]
public record GettingEventsOrderCancelled(string OrderId, string Reason);
public class GettingEventsOrderHistoryReader(IEventLog eventLog)
{
public async Task<IImmutableList<AppendedEvent>> GetOrderEvents(EventSourceId orderId)
{
// Filters the timeline to only the order events you care about.
var eventTypes = new[]
{
typeof(GettingEventsOrderPlaced).GetEventType(),
typeof(GettingEventsOrderCancelled).GetEventType()
};
return await eventLog.GetForEventSourceIdAndEventTypes(orderId, eventTypes);
}
}

View C# snippet source on GitHub

The .NET example filters by event source and event types. Kotlin supports an optional event-source filter on getFromSequenceNumber, and Java’s blocking wrapper accepts it too. Use TypeScript’s getForEventSourceIdAndEventTypes to filter by event source and event types. Elixir provides get_for_event_source/3.

using Cratis.Chronicle.Events;
using Cratis.Chronicle.EventSequences;
using System.Collections.Immutable;
public class GettingEventsReplayEvents(IEventLog eventLog)
{
public async Task<IImmutableList<AppendedEvent>> ReadFrom(EventSequenceNumber sequenceNumber)
{
// Replays from a known checkpoint to rebuild projections or read models.
return await eventLog.GetFromSequenceNumber(sequenceNumber);
}
}

View C# snippet source on GitHub

The start position is inclusive: passing the last processed sequence number reads it again if it matches the filters. Save the next unread position when you want to resume without rereading that event. Kotlin, Java, and TypeScript expose getFromSequenceNumber; Elixir exposes get_from_sequence_number/3.

using Cratis.Chronicle.Events;
using Cratis.Chronicle.EventSequences;
using System.Collections.Immutable;
using System.Linq;
public class GettingEventsTailReader(IEventLog eventLog)
{
public async Task<IImmutableList<AppendedEvent>> ReadLast(int count)
{
// Reads from the computed start and trims in memory to the requested count.
var tail = await eventLog.GetTailSequenceNumber();
var start = tail.IsActualValue && tail.Value >= (ulong)count
? tail - (count - 1)
: EventSequenceNumber.First;
var events = await eventLog.GetFromSequenceNumber(start);
return events.TakeLast(count).ToImmutableList();
}
}

View C# snippet source on GitHub

This .NET example calculates a start position from the tail, reads forward, and trims the result in memory. It does not limit the server response to that count. Use GetLatest for a bounded newest-first read, or Getting state if you need only the tail sequence number.