Skip to content

Read

Reading is how data comes back out. Four things you can do:

  • Read one stream, its records in order, forwards or backwards.
  • Read everything, every record across every stream, in the order it was written.
  • Fetch a single record, one record at a known position, or the first or last of a stream.
  • Follow a live tail, a read that never ends and keeps delivering as records arrive.

Reads are lazy. The server streams results as you consume them, so nothing buffers a whole stream into memory, and you can stop early by breaking out of the loop.

await foreach (var item in client.Streams.ReadStream("order-123")) {
item.Switch(
record => Console.WriteLine("{0} at {1}", record.TypeName, record.Revision),
checkpoint => { });
}

What comes back is a mix of two things. Most items are records. Some are checkpoints, barriers that mark progress. A FilterCheckpoint carries the scan watermark, and a CaughtUpCheckpoint says you have reached the end of the data. They exist so a filtered or slow read can still tell you it is alive and how far it has scanned.

When you only want the records, drop the checkpoints and collect:

List<Record> records = await client.Streams.ReadStream("order-123").ToListAsync();

Reach for that on a short stream you intend to hold in memory. Stay with await foreach for anything long.

The request controls where you start, which direction you travel, how much you take, and how much work the client does per record.

Setting What it decides
Start The revision to begin at. Defaults to the natural edge for the direction
Direction Forwards from the start, or Backwards from the end
Limit Stop after this many records
Filter Which records the read returns at all
FilterMaxSearchWindow How far the server scans for a match before yielding
SkipDecoding Leave payloads as raw bytes, when you only need positions and metadata
ThrowOnUnresolved Throw instead of returning a record whose schema name has no mapping

Reading newest-first is a backwards read anchored at the end. It is the shape you want for “what happened most recently”:

var options = new ReadStreamOptions {
Start = Revision.Max,
Direction = ReadDirection.Backwards,
Limit = 10
};
await foreach (var item in client.Streams.ReadStream("order-123", options)) { … }

SkipDecoding is worth knowing about when you are scanning rather than processing. Deserialising every payload to count records or find a position is wasted work.

The global log holds every record from every stream, in the order the server committed them. This is what you read when you are building a projection, feeding a downstream system, or looking for something without knowing which stream it is in.

await foreach (var item in client.Streams.ReadRecords(LogPosition.Earliest)) { … }

Start at Earliest to replay history, Latest to pick up only what comes next, or From(position) to resume from where you stopped. The same shaping settings apply as for a single stream.

Reading the whole log unfiltered is expensive. When you want a slice of it, a filter narrows it server-side rather than shipping everything to you. A slice is one category, one schema type, or one indexed field.

Three calls return exactly one record.

Record at42 = await client.Streams.InspectRecord(LogPosition.From(42));
Record first = await client.Streams.FirstRecord("order-123");
Record last = await client.Streams.LastRecord("order-123", skipDecoding: true);

InspectRecord answers “what is at this position”. Reach for it when a checkpoint or a log entry gave you a position and you want to see what it points at.

FirstRecord and LastRecord give you the edges of a stream. LastRecord is the one you will actually use: it is how you find the current revision before an append that needs optimistic concurrency.

Pass no stream and you get the edges of the whole log:

Record oldest = await client.Streams.FirstRecord();
Record newest = await client.Streams.LastRecord();

InspectRecord skips decoding by default, since inspecting a position usually means you want the metadata. FirstRecord and LastRecord decode by default.

A subscription is a read that does not finish. It delivers history first, tells you when you have caught up, then keeps delivering as records are written.

Doing this properly means more than a loop: remembering where you got to, resuming there after a restart, reconnecting when the server goes away, and not reprocessing everything on every deploy. That is what a processor is. It owns the subscription, the checkpoints, and the reconnection, and leaves you writing a handler.

Use a processor. Subscribe is the primitive underneath it, and it is documented here so you can see what a processor is doing for you, not as the recommended path.

var options = new SubscribeOptions {
Start = LogPosition.Latest,
Filter = RecordFilter.ByCategory("orders")
};
await foreach (var item in client.Streams.Subscribe(options)) {
item.Switch(
connected => { }, // the subscription is live
record => Handle(record),
checkpoint => { }); // progress, including caught-up
}

A subscription yields three things rather than two. Connected arrives once when the subscription is established, Record is your data, and Checkpoint carries progress.

Setting What it decides
Start Where to begin. Defaults to Latest, so history is skipped unless you ask for it
Filter Which records the subscription delivers
SkipDecoding Leave payloads as raw bytes
ThrowOnUnresolved Fail on a schema name with no mapped type, rather than passing it through raw
FilterMaxSearchWindow Records scanned per filter page before a checkpoint is emitted

What you take on by using it directly: storing the position yourself, resuming from it after a restart, reconnecting when the server goes away, and making sure a redeploy does not replay from the beginning. None of that is provided here.

A read throws when you first iterate it, not when you call it. The call only builds the sequence. Wrap the await foreach, not the line that creates it:

try {
await foreach (var item in client.Streams.ReadStream("order-123", options)) { … }
}
catch (StreamNotFoundException) {
// surfaced from the enumerator
}
Exception What happened
StreamNotFoundException The stream does not exist, or was soft-deleted
StreamTombstonedException The stream was tombstoned
LogPositionNotFoundException Nothing lives at that log position
OperationCanceledException Your cancellation token fired mid-read