This is documentation for the LevelDB implementation of thePersistence QueryAPI. Note that implementations for other journals may have different semantics.
Warning: This module is marked as“experimental”as of its introduction in Akka 2.4.0. We will continue to improve this API based on our users’ feedback, which implies that while we try to keep incompatible changes to a minimum the binary compatibility guarantee for maintenance releases does not apply to the contents of theakka.persistence.querypackage.
3.11.1 Dependencies
Akka persistence LevelDB query implementation is bundled in theakka-persistence-query-experimental artifact. Make sure that you have the following dependency in your project:
"com.typesafe.akka" %% "akka-persistence-query-experimental" % "2.4.10"
3.11.2 How to get the ReadJournal
TheReadJournalis retrieved via theakka.persistence.query.PersistenceQueryextension:
import akka.persistence.query.PersistenceQuery
import akka.persistence.query.journal.leveldb.scaladsl.LeveldbReadJournal val queries = PersistenceQuery(system).readJournalFor[LeveldbReadJournal](
LeveldbReadJournal.Identifier)
3.11.3 Supported Queries
EventsByPersistenceIdQuery and CurrentEventsByPersistenceIdQuery
eventsByPersistenceId is used for retrieving events for a specific PersistentActor identified by persistenceId.
implicit val mat = ActorMaterializer()(system)
val queries = PersistenceQuery(system).readJournalFor[LeveldbReadJournal](
LeveldbReadJournal.Identifier)
val src: Source[EventEnvelope, NotUsed] =
queries.eventsByPersistenceId("some-persistence-id", 0L, Long.MaxValue) val events: Source[Any, NotUsed] = src.map(_.event)
You can retrieve a subset of all events by specifyingfromSequenceNrandtoSequenceNror use0Land Long.MaxValuerespectively to retrieve all events. Note that the corresponding sequence number of each event is provided in theEventEnvelope, which makes it possible to resume the stream at a later point from a given sequence number.
3.11. Persistence Query for LevelDB 214
The returned event stream is ordered by sequence number, i.e. the same order as thePersistentActor persisted the events. The same prefix of stream elements (in same order) are returned for multiple executions of the query, except for when events have been deleted.
The stream is not completed when it reaches the end of the currently stored events, but it continues to push new events when new events are persisted. Corresponding query that is completed when it reaches the end of the currently stored events is provided bycurrentEventsByPersistenceId.
The LevelDB write journal is notifying the query side as soon as events are persisted, but for efficiency reasons the query side retrieves the events in batches that sometimes can be delayed up to the configured refresh-intervalor givenRefreshIntervalhint.
The stream is completed with failure if there is a failure in executing the query in the backend journal.
AllPersistenceIdsQuery and CurrentPersistenceIdsQuery
allPersistenceIdsis used for retrieving allpersistenceIdsof all persistent actors.
implicit val mat = ActorMaterializer()(system)
val queries = PersistenceQuery(system).readJournalFor[LeveldbReadJournal](
LeveldbReadJournal.Identifier)
val src: Source[String, NotUsed] = queries.allPersistenceIds()
The returned event stream is unordered and you can expect different order for multiple executions of the query.
The stream is not completed when it reaches the end of the currently usedpersistenceIds, but it continues to push newpersistenceIdswhen new persistent actors are created. Corresponding query that is completed when it reaches the end of the currently usedpersistenceIdsis provided bycurrentPersistenceIds.
The LevelDB write journal is notifying the query side as soon as newpersistenceIdsare created and there is no periodic polling or batching involved in this query.
The stream is completed with failure if there is a failure in executing the query in the backend journal.
EventsByTag and CurrentEventsByTag
eventsByTagis used for retrieving events that were marked with a given tag, e.g. all domain events of an Aggregate Root type.
implicit val mat = ActorMaterializer()(system)
val queries = PersistenceQuery(system).readJournalFor[LeveldbReadJournal](
LeveldbReadJournal.Identifier)
val src: Source[EventEnvelope, NotUsed] =
queries.eventsByTag(tag = "green", offset = 0L)
To tag events you create an Event Adapters that wraps the events in a
akka.persistence.journal.Taggedwith the giventags.
import akka.persistence.journal.WriteEventAdapter import akka.persistence.journal.Tagged
class MyTaggingEventAdapter extends WriteEventAdapter { val colors = Set("green", "black", "blue")
override def toJournal(event: Any): Any = event match { case s: String =>
var tags = colors.foldLeft(Set.empty[String]) { (acc, c) =>
if (s.contains(c)) acc + c else acc }
if (tags.isEmpty) event else Tagged(event, tags)
3.11. Persistence Query for LevelDB 215
case _ => event }
override def manifest(event: Any): String = ""
}
You can retrieve a subset of all events by specifyingoffset, or use0Lto retrieve all events with a given tag.
Theoffsetcorresponds to an ordered sequence number for the specific tag. Note that the corresponding offset of each event is provided in theEventEnvelope, which makes it possible to resume the stream at a later point from a given offset.
In addition to theoffsettheEventEnvelopealso providespersistenceIdandsequenceNrfor each event. ThesequenceNris the sequence number for the persistent actor with thepersistenceIdthat per- sisted the event. ThepersistenceId+sequenceNris an unique identifier for the event.
The returned event stream is ordered by the offset (tag sequence number), which corresponds to the same order as the write journal stored the events. The same stream elements (in same order) are returned for multiple executions of the query. Deleted events are not deleted from the tagged event stream.
Note: Events deleted usingdeleteMessages(toSequenceNr)are not deleted from the “tagged stream”.
The stream is not completed when it reaches the end of the currently stored events, but it continues to push new events when new events are persisted. Corresponding query that is completed when it reaches the end of the currently stored events is provided bycurrentEventsByTag.
The LevelDB write journal is notifying the query side as soon as tagged events are persisted, but for effi- ciency reasons the query side retrieves the events in batches that sometimes can be delayed up to the configured refresh-intervalor givenRefreshIntervalhint.
The stream is completed with failure if there is a failure in executing the query in the backend journal.
3.11.4 Configuration
Configuration settings can be defined in the configuration section with the absolute path correspond- ing to the identifier, which is "akka.persistence.query.journal.leveldb" for the default LeveldbReadJournal.Identifier.
It can be configured with the following properties:
# Configuration for the LeveldbReadJournal akka.persistence.query.journal.leveldb {
# Implementation class of the LevelDB ReadJournalProvider
class = "akka.persistence.query.journal.leveldb.LeveldbReadJournalProvider"
# Absolute path to the write journal plugin configuration entry that this
# query journal will connect to. That must be a LeveldbJournal or
˓→SharedLeveldbJournal.
# If undefined (or "") it will connect to the default journal as specified by the
# akka.persistence.journal.plugin property.
write-plugin = ""
# The LevelDB write journal is notifying the query side as soon as things
# are persisted, but for efficiency reasons the query side retrieves the events
# in batches that sometimes can be delayed up to the configured `refresh-
˓→interval`.
refresh-interval = 3s
# How many events to fetch in one query (replay) and keep buffered until they
# are delivered downstreams.
3.11. Persistence Query for LevelDB 216
max-buffer-size = 100 }