157 lines
6.8 KiB
ReStructuredText
157 lines
6.8 KiB
ReStructuredText
|
.. _persistence-query-leveldb-scala:
|
|||
|
|
|
|||
|
|
#############################
|
|||
|
|
Persistence Query for LevelDB
|
|||
|
|
#############################
|
|||
|
|
|
|||
|
|
This is documentation for the LevelDB implementation of the :ref:`persistence-query-scala` API.
|
|||
|
|
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 the ``akka.persistence.query`` package.
|
|||
|
|
|
|||
|
|
Dependencies
|
|||
|
|
============
|
|||
|
|
|
|||
|
|
Akka persistence LevelDB query implementation is bundled in the ``akka-persistence-query-experimental`` artifact.
|
|||
|
|
Make sure that you have the following dependency in your project::
|
|||
|
|
|
|||
|
|
"com.typesafe.akka" %% "akka-persistence-query-experimental" % "@version@" @crossString@
|
|||
|
|
|
|||
|
|
How to get the ReadJournal
|
|||
|
|
==========================
|
|||
|
|
|
|||
|
|
The ``ReadJournal`` is retrieved via the ``akka.persistence.query.PersistenceQuery``
|
|||
|
|
extension:
|
|||
|
|
|
|||
|
|
.. includecode:: code/docs/persistence/query/LeveldbPersistenceQueryDocSpec.scala#get-read-journal
|
|||
|
|
|
|||
|
|
Supported Queries
|
|||
|
|
=================
|
|||
|
|
|
|||
|
|
EventsByPersistenceId
|
|||
|
|
---------------------
|
|||
|
|
|
|||
|
|
``EventsByPersistenceId`` is used for retrieving events for a specific ``PersistentActor``
|
|||
|
|
identified by ``persistenceId``.
|
|||
|
|
|
|||
|
|
.. includecode:: code/docs/persistence/query/LeveldbPersistenceQueryDocSpec.scala#EventsByPersistenceId
|
|||
|
|
|
|||
|
|
You can retrieve a subset of all events by specifying ``fromSequenceNr`` and ``toSequenceNr``
|
|||
|
|
or use ``0L`` and ``Long.MaxValue`` respectively to retrieve all events. Note that
|
|||
|
|
the corresponding sequence number of each event is provided in the ``EventEnvelope``,
|
|||
|
|
which makes it possible to resume the stream at a later point from a given sequence number.
|
|||
|
|
|
|||
|
|
The returned event stream is ordered by sequence number, i.e. the same order as the
|
|||
|
|
``PersistentActor`` 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 query supports two different completion modes:
|
|||
|
|
|
|||
|
|
* 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. This is the
|
|||
|
|
default mode that is used when no hints are given. It can also be specified with
|
|||
|
|
hint ``RefreshInterval``.
|
|||
|
|
|
|||
|
|
* The stream is completed when it reaches the end of the currently stored events.
|
|||
|
|
This mode is specified with hint ``NoRefresh``.
|
|||
|
|
|
|||
|
|
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-interval`` or given ``RefreshInterval``
|
|||
|
|
hint.
|
|||
|
|
|
|||
|
|
The stream is completed with failure if there is a failure in executing the query in the
|
|||
|
|
backend journal.
|
|||
|
|
|
|||
|
|
AllPersistenceIds
|
|||
|
|
-----------------
|
|||
|
|
|
|||
|
|
``AllPersistenceIds`` is used for retrieving all ``persistenceIds`` of all persistent actors.
|
|||
|
|
|
|||
|
|
.. includecode:: code/docs/persistence/query/LeveldbPersistenceQueryDocSpec.scala#AllPersistenceIds
|
|||
|
|
|
|||
|
|
The returned event stream is unordered and you can expect different order for multiple
|
|||
|
|
executions of the query.
|
|||
|
|
|
|||
|
|
The query supports two different completion modes:
|
|||
|
|
|
|||
|
|
* The stream is not completed when it reaches the end of the currently used ``persistenceIds``,
|
|||
|
|
but it continues to push new ``persistenceIds`` when new persistent actors are created.
|
|||
|
|
This is the default mode that is used when no hints are given. It can also be specified with
|
|||
|
|
hint ``RefreshInterval``.
|
|||
|
|
|
|||
|
|
* The stream is completed when it reaches the end of the currently used ``persistenceIds``.
|
|||
|
|
This mode is specified with hint ``NoRefresh``.
|
|||
|
|
|
|||
|
|
The LevelDB write journal is notifying the query side as soon as new ``persistenceIds`` are
|
|||
|
|
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
|
|||
|
|
-----------
|
|||
|
|
|
|||
|
|
``EventsByTag`` is used for retrieving events that were marked with a given tag, e.g.
|
|||
|
|
all domain events of an Aggregate Root type.
|
|||
|
|
|
|||
|
|
.. includecode:: code/docs/persistence/query/LeveldbPersistenceQueryDocSpec.scala#EventsByTag
|
|||
|
|
|
|||
|
|
To tag events you create an :ref:`event-adapters-scala` that wraps the events in a ``akka.persistence.journal.leveldb.Tagged``
|
|||
|
|
with the given ``tags``.
|
|||
|
|
|
|||
|
|
.. includecode:: code/docs/persistence/query/LeveldbPersistenceQueryDocSpec.scala#tagger
|
|||
|
|
|
|||
|
|
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 an ordered sequence number for the specific tag.
|
|||
|
|
Note that the corresponding offset of each event is provided in the ``EventEnvelope``, which makes it possible
|
|||
|
|
to resume the stream at a later point from a given offset.
|
|||
|
|
|
|||
|
|
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 (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 using ``deleteMessages(toSequenceNr)`` are not deleted from the "tagged stream".
|
|||
|
|
|
|||
|
|
The query supports two different completion modes:
|
|||
|
|
|
|||
|
|
* 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. This is the
|
|||
|
|
default mode that is used when no hints are given. It can also be specified with
|
|||
|
|
hint ``RefreshInterval``.
|
|||
|
|
|
|||
|
|
* The stream is completed when it reaches the end of the currently stored events.
|
|||
|
|
This mode is specified with hint ``NoRefresh``.
|
|||
|
|
|
|||
|
|
The LevelDB write journal is notifying the query side as soon as tagged 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-interval`` or given ``RefreshInterval``
|
|||
|
|
hint.
|
|||
|
|
|
|||
|
|
The stream is completed with failure if there is a failure in executing the query in the
|
|||
|
|
backend journal.
|
|||
|
|
|
|||
|
|
Configuration
|
|||
|
|
=============
|
|||
|
|
|
|||
|
|
Configuration settings can be defined in the configuration section with the
|
|||
|
|
absolute path corresponding to the identifier, which is ``"akka.persistence.query.journal.leveldb"``
|
|||
|
|
for the default ``LeveldbReadJournal.Identifier``.
|
|||
|
|
|
|||
|
|
It can be configured with the following properties:
|
|||
|
|
|
|||
|
|
.. includecode:: ../../../akka-persistence-query/src/main/resources/reference.conf#query-leveldb
|