akka.persistence.cassandra.query.javadsl
allPersistenceIds
is used to retrieve a stream of persistenceId
s.
allPersistenceIds
is used to retrieve a stream of persistenceId
s.
The stream emits persistenceId
strings.
The stream guarantees that a persistenceId
is only emitted once and there are no duplicates.
Order is not defined. Multiple executions of the same stream (even bounded) may emit different
sequence of persistenceId
s.
The stream is not completed when it reaches the end of the currently known persistenceId
s,
but it continues to push new persistenceId
s when new events are persisted.
Corresponding query that is completed when it reaches the end of the currently
known persistenceId
s is provided by currentPersistenceIds
.
Note the query is inefficient, especially for large numbers of persistenceId
s, because
of limitation of current internal implementation providing no information supporting
ordering/offset queries. The query uses Cassandra's select distinct
capabilities.
More importantly the live query has to repeatedly execute the query each refresh-interval
,
because order is not defined and new persistenceId
s may appear anywhere in the query results.
Same type of query as eventsByPersistenceId
but the event stream
is completed immediately when it reaches the end of the "result set".
Same type of query as eventsByPersistenceId
but the event stream
is completed immediately when it reaches the end of the "result set". Events that are
stored after the query is completed are not included in the event stream.
Same type of query as the currentEventsByTag
query with Long
offset, but this one has
a time based UUID offset
.
Same type of query as the currentEventsByTag
query with Long
offset, but this one has
a time based UUID offset
. This query is better for cases where you want to resume
the stream from an exact point without receiving duplicate events for the same
timestamp.
Use #firstOffset when you want all events from the beginning of time.
The offset
is exclusive, i.e. the event with the exact same UUID will not be included
in the returned stream.
Same type of query as eventsByTag
but the event stream
is completed immediately when it reaches the end of the "result set".
Same type of query as eventsByTag
but the event stream
is completed immediately when it reaches the end of the "result set". Events that are
stored after the query is completed are not included in the event stream.
The offset
is inclusive, i.e. the events with the exact same timestamp will be included
in the returned stream.
Same type of query as eventsByTag
but the event stream
is completed immediately when it reaches the end of the "result set".
Same type of query as eventsByTag
but the event stream
is completed immediately when it reaches the end of the "result set". Events that are
stored after the query is completed are not included in the event stream.
Use NoOffset
when you want all events from the beginning of time.
To acquire an offset from a long unix timestamp to use with this query, you can use #timeBasedUUIDFrom.
Same type of query as allPersistenceIds
but the event stream
is completed immediately when it reaches the end of the "result set".
Same type of query as allPersistenceIds
but the event stream
is completed immediately when it reaches the end of the "result set". Events that are
stored after the query is completed are not included in the event stream.
eventsByPersistenceId
is used to retrieve a stream of events for a particular persistenceId.
eventsByPersistenceId
is used to retrieve a stream of events for a particular persistenceId.
In addition to the offset
the EventEnvelope
also provides persistenceId
and sequenceNr
for each event. The sequenceNr
is the sequence number for the persistent actor with the
persistenceId
that persisted the event. The persistenceId
+ sequenceNr
is an unique
identifier for the event.
sequenceNr
and offset
are always the same for an event and they define ordering for events
emitted by this query. Causality is guaranteed (sequenceNr
s of events for a particular
persistenceId
are always ordered in a sequence monotonically increasing by one). Multiple
executions of the same bounded stream are guaranteed to emit exactly the same stream of events.
fromSequenceNr
and toSequenceNr
can be specified to limit the set of returned events.
The fromSequenceNr
and toSequenceNr
are inclusive.
Deleted events are also deleted from the event 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 by currentEventsByPersistenceId
.
Same type of query as the eventsByTag
query with Long
offset, but this one has
a time based UUID offset
.
Same type of query as the eventsByTag
query with Long
offset, but this one has
a time based UUID offset
. This query is better for cases where you want to resume
the stream from an exact point without receiving duplicate events for the same
timestamp.
Use #firstOffset when you want all events from the beginning of time.
The offset
is exclusive, i.e. the event with the exact same UUID will not be included
in the returned stream.
eventsByTag
is used for retrieving events that were marked with
a given tag, e.g.
eventsByTag
is used for retrieving events that were marked with
a given tag, e.g. all events of an Aggregate Root type.
To tag events you create an akka.persistence.journal.EventAdapter
that wraps the events
in a akka.persistence.journal.Tagged
with the given tags
.
The tags must be defined in the tags
section of the cassandra-journal
configuration.
Max 3 tags per event is supported.
You can retrieve a subset of all events by specifying offset
, or use 0L
to retrieve all
events with a given tag. The offset
corresponds to a timesamp of the events. Note that the
corresponding offset of each event is provided in the akka.persistence.query.EventEnvelope
,
which makes it possible to resume the stream at a later point from a given offset.
The offset
is inclusive, i.e. the events with the exact same timestamp will be included
in the returned stream.
There is a variant of this query with a time based UUID as offset. That query is better for cases where you want to resume the stream from an exact point without receiving duplicate events for the same timestamp.
In addition to the offset
the EventEnvelope
also provides persistenceId
and sequenceNr
for each event. The sequenceNr
is the sequence number for the persistent actor with the
persistenceId
that persisted the event. The persistenceId
+ sequenceNr
is an unique
identifier for the event.
The returned event stream is ordered by the offset (timestamp), which corresponds
to the same order as the write journal stored the events, with inaccuracy due to clock skew
between different nodes. The same stream elements (in same order) are returned for multiple
executions of the query on a best effort basis. The query is using a Cassandra Materialized
View for the query and that is eventually consistent, so different queries may see different
events for the latest events, but eventually the result will be ordered by timestamp
(Cassandra timeuuid column). To compensate for the the eventual consistency the query is
delayed to not read the latest events, see cassandra-query-journal.eventual-consistency-delay
in reference.conf. However, this is only best effort and in case of network partitions
or other things that may delay the updates of the Materialized View the events may be
delivered in different order (not strictly by their timestamp).
For each persistenceId
the events are delivered strictly by sequence number. If
a sequence number is missing the query is delayed up to the configured
delayed-event-timeout
and if the expected event is still not found
the stream is completed with failure.
If you use the same tag for all events for a persistenceId
it is possible to get
a more strict delivery order than otherwise. This can be useful when all events of
a PersistentActor class (all events of all instances of that PersistentActor class)
are tagged with the same tag. Then the events for each persistenceId
can be delivered
strictly by sequence number. If a sequence number is missing the query is delayed up
to the configured delayed-event-timeout
and if the expected event is still not
found the stream is completed with failure. This means that there must not be any
holes in the sequence numbers for a given tag, i.e. all events must be tagged
with the same tag. Set delayed-event-timeout
to for example 30s to enable this
feature. It is disabled by default.
Deleted events are also deleted from the tagged event 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 by currentEventsByTag
.
The stream is completed with failure if there is a failure in executing the query in the backend journal.
eventsByTag
is used for retrieving events that were marked with
a given tag, e.g.
eventsByTag
is used for retrieving events that were marked with
a given tag, e.g. all events of an Aggregate Root type.
To tag events you create an akka.persistence.journal.EventAdapter
that wraps the events
in a akka.persistence.journal.Tagged
with the given tags
.
The tags must be defined in the tags
section of the cassandra-journal
configuration.
Max 3 tags per event is supported.
You can use NoOffset
to retrieve all events with a given tag or
retrieve a subset of all events by specifying a TimeBasedUUID
offset
.
The offset of each event is provided in the streamed envelopes returned, which makes it possible to resume the stream at a later point from a given offset.
For querying events that happened after a long unix timestamp you can use #timeBasedUUIDFrom to create the offset to use with this method.
In addition to the offset
the envelope also provides persistenceId
and sequenceNr
for each event. The sequenceNr
is the sequence number for the persistent actor with the
persistenceId
that persisted the event. The persistenceId
+ sequenceNr
is an unique
identifier for the event.
The returned event stream is ordered by the offset (timestamp), which corresponds
to the same order as the write journal stored the events, with inaccuracy due to clock skew
between different nodes. The same stream elements (in same order) are returned for multiple
executions of the query on a best effort basis. The query is using a Cassandra Materialized
View for the query and that is eventually consistent, so different queries may see different
events for the latest events, but eventually the result will be ordered by timestamp
(Cassandra timeuuid column). To compensate for the the eventual consistency the query is
delayed to not read the latest events, see cassandra-query-journal.eventual-consistency-delay
in reference.conf. However, this is only best effort and in case of network partitions
or other things that may delay the updates of the Materialized View the events may be
delivered in different order (not strictly by their timestamp).
If you use the same tag for all events for a persistenceId
it is possible to get
a more strict delivery order than otherwise. This can be useful when all events of
a PersistentActor class (all events of all instances of that PersistentActor class)
are tagged with the same tag. Then the events for each persistenceId
can be delivered
strictly by sequence number. If a sequence number is missing the query is delayed up
to the configured delayed-event-timeout
and if the expected event is still not
found the stream is completed with failure. This means that there must not be any
holes in the sequence numbers for a given tag, i.e. all events must be tagged
with the same tag. Set delayed-event-timeout
to for example 30s to enable this
feature. It is disabled by default.
Deleted events are also deleted from the tagged event 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 by currentEventsByTag
.
The stream is completed with failure if there is a failure in executing the query in the backend journal.
Use this as the UUID offset in eventsByTag
queries when you want all
events from the beginning of time.
Create a time based UUID that can be used as offset in eventsByTag
queries.
Create a time based UUID that can be used as offset in eventsByTag
queries. The timestamp
is a unix timestamp (as returned by
System#currentTimeMillis
.
Data Access Object for arbitrary queries or updates.
Java API:
akka.persistence.query.javadsl.ReadJournal
implementation for Cassandra.It is retrieved with:
CassandraReadJournal queries = PersistenceQuery.get(system).getReadJournalFor(CassandraReadJournal.class, CassandraReadJournal.Identifier());
Corresponding Scala API is in akka.persistence.cassandra.query.scaladsl.CassandraReadJournal.
Configuration settings can be defined in the configuration section with the absolute path corresponding to the identifier, which is
"cassandra-query-journal"
for the default CassandraReadJournal#Identifier. Seereference.conf
.