Table of Contents

Interface IGlobalStreamQuery

Namespace
Excalibur.EventSourcing.Queries
Assembly
Excalibur.EventSourcing.dll

Provides cross-aggregate event querying capabilities over the global event stream.

public interface IGlobalStreamQuery

Remarks

The global stream query enables reading events across all aggregates, which is essential for:

  • Building cross-aggregate projections
  • Event-driven integrations that need all events
  • Audit and compliance reporting
  • Event replay for projection rebuilding

Events are returned in global order (as committed). Use GlobalStreamPosition to track reading progress and resume from a checkpoint.

Methods

GetHeadPositionAsync(CancellationToken)

Gets the current head position of the global stream — the position of the most recently committed event across all aggregates.

ValueTask<long> GetHeadPositionAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

Cancellation token.

Returns

ValueTask<long>

The highest committed global-stream position, or 0 when the stream is empty.

Remarks

Pairing the head with a subscription's checkpoint yields the subscription's projection lag.

ReadAllAsync(GlobalStreamPosition, int, CancellationToken)

Reads events from the global stream lying STRICTLY ABOVE the specified position.

ValueTask<IReadOnlyList<StoredEvent>> ReadAllAsync(GlobalStreamPosition position, int maxCount, CancellationToken cancellationToken)

Parameters

position GlobalStreamPosition

The exclusive lower bound. The event at this position is NOT returned; reading resumes at the next one.

maxCount int

The maximum number of events to return.

cancellationToken CancellationToken

Cancellation token.

Returns

ValueTask<IReadOnlyList<StoredEvent>>

The events strictly above position, in ascending global order, with no duplicates.

Remarks

Exclusivity is a contract, not an implementation detail, and a consumer of this interface relies on it for correctness. A subscription records its progress as the position it has applied through, and resumes by passing that position here. An implementation that returned the event AT the given position would redeliver the last applied event on every single poll, and a subscription would never make progress past it.

It also decides what counts as a re-delivery. Because every event returned here is above the caller's own recorded progress, a reader resuming from its checkpoint knows that nothing it receives has been applied before — which is why the projection host can state that its deliveries are first deliveries rather than having to compute it. An inclusive implementation silently breaks that reasoning.

Implementers: the bound is >, never >=. Ascending order and absence of duplicates are required, and a position must not be returned before every position below it is committed — a reader cannot distinguish a gap that will fill from one that never will, so returning past a gap converts a transient hole into a permanently skipped event.

ReadByEventTypeAsync(string, GlobalStreamPosition, int, CancellationToken)

Reads events of a specific type from the global stream starting at the specified position.

ValueTask<IReadOnlyList<StoredEvent>> ReadByEventTypeAsync(string eventType, GlobalStreamPosition position, int maxCount, CancellationToken cancellationToken)

Parameters

eventType string

The event type name to filter by.

position GlobalStreamPosition

The position to start reading from.

maxCount int

The maximum number of events to return.

cancellationToken CancellationToken

Cancellation token.

Returns

ValueTask<IReadOnlyList<StoredEvent>>

The events of the specified type in global order.

Remarks

Selection is made when the underlying page is read. If archive hydration subsequently observes that a selected event was erased, that row may be returned as a normalized erasure marker with no payload or metadata, retaining its identity and position. Consumers must handle such markers even when requesting a different event type. A page is not an atomic snapshot across hydration.