liveBook · Manning

eventsByTag

As explained in Akka in Action, Second Edition

The eventsByTag stream is a Persistence Query stream that emits persisted events associated with a specified tag.

eventsByTag reads persisted events that share a tag from a Persistence Query read journal. Supply the tag and an offset; Offset.noOffset starts at the beginning of the journal. The query produces a Source of EventEnvelope values, each carrying journal ordering, persistence ID, sequence number, event payload, and timestamp. section 10.2

Read tagged container events

A JDBC read journal can query "container-tag-0" with Offset.noOffset. That tag selects the first two CargoAdded events for persistence ID spcontainer-type-key|9; the returned envelopes expose both the event and its journal position. section 10.2

Tags make a journal useful beyond inspecting stored events:

  • Filter for event types or business categories, such as CargoAdded, rather than processing every journal entry. section 10.2
  • Partition event processing: separate tag streams can run in parallel, including on different machines. section 10.2
  • Build a read-side result by aggregating tagged events, then write it to a separate database or topic. section 10.2.1
  • Enrich events after reading them and route transformed results through a pipes-and-filters flow. section 10.2.1

A typical read-side use case calculates total container weight from AddCargo events and upserts the result into another store. Keeping that derived value outside the persistent container avoids predicting every future query and decouples event writing from read-side aggregation. Clustering is optional for the query itself, but supports fault tolerance and scalable processing. section 10.2.1

Akka Projections package this query as an event source provider. A projection selects eventsByTag through its read-journal plugin and tag, then delegates writes to a handler. It manages offsets on restart with effectively-once delivery semantics and can configure parallelism, bounded by the available persistence entity tags. section 10.3 section 10.3.1

Table 10.1 Methods available to consume the journal: inputs and outputs (view table figure)

Interface methods

Input

Output

eventsByTag

currentEventsByTag

tag: String

offset: Int

List[EventEnvelope]

persistenceIds

currentPersistenceIds

List[String]

eventsByPersistenceId

currentEventsByPersistenceId

id: String

from: Int

to: Int

List[EventEnvelope]

Compare eventsByTag with currentEventsByTag and the other journal queries by their inputs and outputs. section 10.2

How Akka in Action, Second Edition covers it

How deep it goes
Explains query inputs, Source[EventEnvelope] output, offsets, tag partitioning, and projection integration without detailing journal internals.
Examples
Uses CargoAdded events, container-tag-0, JDBC storage, total container weight aggregation, and a CargosPerContainerProjection.
What it assumes
Assumes persisted events, an ActorSystem, a configured ReadJournal, and knowledge of the tags an application generates.
What you can do after
Apply it via Akka Persistence Query or projections to select tagged events and build a separate read-side result.
How it connects
Connects Persistence Query with ReadJournal, Offset, EventEnvelope, Akka Projections, EventSourcedProvider, upserts, and persistence entity tags.
Cover of Akka in Action, Second Edition
liveBookmanning.com
Read Akka in Action, Second Edition on liveBook Get the book at manning.com

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Akka in Action, Second Edition. The section links point to the parts of the book it draws on.