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:

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.