Rebuilding Projections with `replay()`
eventsource.application.projections.replay (also re-exported from the top-level eventsource package) rebuilds one or more projections by reading the event store's global feed (GlobalEventFeed) and folding every matching event into each projection in order:
- Single-projection or multi-projection rebuilds: pass a single
EventSubscriberdirectly (await replay(store, my_projection)) or a sequence of projections (await replay(store, [orders, invoices])). ReplayReport.succeeded: boolean property returningTruewhen the rebuild completed with zero failures (len(report.failures) == 0andreport.failures_truncated == 0).- Storage-level filtering: scope rebuilds with
tenant_id=...,aggregate_type=..., andfrom_position=...pushed down to the store query viaFeedReadOptions. - Resilient or strict error handling: record poison events in
report.failureswhile continuing the rebuild by default, or passstrict=Trueto raiseReplayFailedErroron the first failure.
For an introductory walkthrough of projections, see Tutorial 6: Projections, How to Work with Read Models, and the Projections API Reference.
Rebuilding a single projection with `replay(store, projection)`
When rebuilding a single projection, pass the projection instance directly as the second argument to replay(store, my_projection) without wrapping it in a list, and check report.succeeded:
from uuid import UUID, uuid4
from eventsource import (
DeclarativeProjection,
DomainEvent,
ExpectedVersion,
InMemoryEventStore,
StreamId,
handles,
replay,
)
class AccountOpened(DomainEvent):
aggregate_type: str = "Account"
owner: str
class MoneyDeposited(DomainEvent):
aggregate_type: str = "Account"
amount: float
class AccountBalanceProjection(DeclarativeProjection):
def __init__(self) -> None:
super().__init__()
self.balances: dict[UUID, float] = {}
@handles(AccountOpened)
async def _on_opened(self, event: AccountOpened) -> None:
self.balances[event.aggregate_id] = 0.0
@handles(MoneyDeposited)
async def _on_deposited(self, event: MoneyDeposited) -> None:
self.balances[event.aggregate_id] = (
self.balances.get(event.aggregate_id, 0.0) + event.amount
)
async def rebuild_single_projection() -> None:
async with InMemoryEventStore() as store:
account_id = uuid4()
await store.append(
StreamId(account_id, "Account"),
[
AccountOpened(
aggregate_id=account_id,
aggregate_version=1,
owner="alice",
),
MoneyDeposited(
aggregate_id=account_id,
aggregate_version=2,
amount=125.0,
),
],
ExpectedVersion.NO_STREAM,
)
projection = AccountBalanceProjection()
# Pass a single projection directly without wrapping in [...]
report = await replay(store, projection)
assert report.succeeded is True
assert report.applied == 2
assert report.failed == 0
assert projection.balances[account_id] == 125.0
Rebuilding multiple projections in a single pass
When rebuilding several projections from the same global event feed, pass a sequence of EventSubscriber instances ([balance_projection, audit_projection]) so the feed is read once and each event is folded into every projection in order:
async def rebuild_multiple_projections(
store: InMemoryEventStore,
balance_projection: AccountBalanceProjection,
audit_projection: AccountBalanceProjection,
) -> None:
report = await replay(store, [balance_projection, audit_projection])
assert report.succeeded is True
print(f"Applied {report.applied} events up to {report.last_position}")
Inspecting rebuild outcomes with `ReplayReport` and `report.succeeded`
replay() returns a frozen ReplayReport summarizing the rebuild:
| Attribute / Property | Type | Description | |
|---|---|---|---|
succeeded |
bool |
True when len(failures) == 0 and failures_truncated == 0; False if any projection rejected an event. |
|
applied |
int |
Count of events delivered that no projection rejected. | |
failed |
int |
Count of distinct events (event_id) rejected by at least one projection in failures. |
|
last_position |
`Position \ | None` | Final global position reached during the read (None when the feed is empty). |
failures |
tuple[ReplayFailure, ...] |
Retained ReplayFailure entries (capped at max_failures, default 1000). |
|
failures_truncated |
int |
Number of additional failures that occurred beyond max_failures. |
|
raise_for_failures() |
() -> None |
Raises ReplayFailedError with the first failure if not succeeded, or RuntimeError when all failures were truncated (max_failures=0). |
By default, a projection raising an exception on a poison event does not halt the rebuild: replay() records a ReplayFailure(position, event_id, event_type, projection, error), sets report.succeeded to False, and continues folding subsequent events:
from eventsource.application.projections import ReplayFailedError, ReplayFailure
async def inspect_replay_failures(
store: InMemoryEventStore,
projection: AccountBalanceProjection,
) -> None:
logged_failures: list[ReplayFailure] = []
report = await replay(
store,
projection,
on_failure=logged_failures.append,
)
if not report.succeeded:
for failure in report.failures:
print(
f"{failure.projection} rejected {failure.event_type} "
f"({failure.event_id}) at {failure.position}: {failure.error}"
)
# Or raise ReplayFailedError after inspecting all collected failures:
report.raise_for_failures()
To fail fast on the first rejected event (for example in tests or initial production deployments), pass strict=True to raise ReplayFailedError:
async def strict_rebuild(
store: InMemoryEventStore,
projection: AccountBalanceProjection,
) -> None:
try:
report = await replay(store, projection, strict=True)
report.raise_for_failures()
except ReplayFailedError as err:
print(f"Rebuild stopped at {err.failure.event_id}: {err.failure.error}")
raise
Scoping rebuilds by tenant, aggregate type, or starting position
Pass tenant_id=..., aggregate_type=..., or from_position=... to push filtering down to the storage adapter via FeedReadOptions instead of scanning the entire log in Python:
from uuid import UUID
from eventsource.ports.positions import Position
async def scoped_rebuild(
store: InMemoryEventStore,
projection: AccountBalanceProjection,
tenant_id: UUID,
checkpoint: Position | None = None,
) -> None:
report = await replay(
store,
projection,
from_position=checkpoint,
tenant_id=tenant_id,
aggregate_type="Account",
)
assert report.succeeded is True
Coordinating batches of events with `ProjectionCoordinator`, `ProjectionRegistry`, and `SubscriberRegistry`
When you already have a batch of DomainEvent instances in memory and want to dispatch or rebuild multiple projections and event handlers concurrently, pass your projections or handlers directly to ProjectionCoordinator([proj1, proj2]) or register them fluently with ProjectionRegistry(projections=[...]).register(...). For subscribers implementing EventSubscriber (subscribed_to()), SubscriberRegistry indexes subscribers by event type at registration time for $O(1)$ lookup via SubscriberRegistry(subscribers=[...]).register(*subscribers).
ProjectionRegistry, ProjectionCoordinator, and SubscriberRegistry all support Pythonic container protocols (len(registry), bool(registry) always True, proj in registry), fluent .register(*items), .unregister(item), and .clear() (plus list(subscriber_registry) iteration on SubscriberRegistry):
from eventsource import ProjectionCoordinator, ProjectionRegistry, SubscriberRegistry
async def coordinate_projections(
balance_projection: AccountBalanceProjection,
events: list[DomainEvent],
) -> None:
# Pass a sequence of projections/handlers directly:
coordinator = ProjectionCoordinator([balance_projection])
assert len(coordinator) == 1
assert balance_projection in coordinator
await coordinator.dispatch_events(events)
# Or configure a ProjectionRegistry with max_concurrency and fluent .register():
registry = ProjectionRegistry(max_concurrency=4).register(balance_projection)
assert balance_projection in registry
bounded_coordinator = ProjectionCoordinator(registry)
await bounded_coordinator.rebuild_all(events)
registry.unregister(balance_projection)
registry.clear()
# Or dispatch only to interested EventSubscribers via O(1) event-type lookup:
subscriber_registry = SubscriberRegistry(subscribers=[balance_projection])
assert balance_projection in subscriber_registry
assert list(subscriber_registry) == [balance_projection]
await subscriber_registry.dispatch_many(events)
subscriber_registry.clear()
Failure behavior of `rebuild_all`
ProjectionCoordinator.rebuild_all raises ProjectionRebuildError when a projection fails. It does not return the event count. The coordinator first dispatches every event, so healthy projections still see the full batch. The error reports failure_count, the number of failed projection calls. The first projection error is the __cause__.
A returned count proves that every projection accepted every event. Catch ProjectionRebuildError to handle a failed rebuild. Use replay() for a per-event failure report:
from eventsource import replay
from eventsource.application.projections.coordinator_projection import (
ProjectionRebuildError,
)
async def rebuild_with_report(coordinator, store, balance_projection, events) -> None:
try:
await coordinator.rebuild_all(events)
except ProjectionRebuildError as err:
print(f"{err.failure_count} projection call(s) failed: {err.__cause__}")
report = await replay(store, balance_projection)
for failure in report.failures:
print(f"{failure.projection} rejected {failure.event_id}: {failure.error}")
dispatch_events and SubscriberRegistry.dispatch_many do not raise on projection failure. They log each error. Check the logs or use replay() when you need to know that a dispatch failed.
Projections also differ on unhandled events. DeclarativeProjection defaults to unregistered_event_handling="ignore". An event type with no @handles method is skipped silently. Set unregistered_event_handling="warn" or "error" to see these events.