156 lines
6.8 KiB
ReStructuredText
156 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.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
|