From e1cc952cf640b28248d2e3029bb2aa85395e3b9c Mon Sep 17 00:00:00 2001 From: PJ Fanning Date: Thu, 8 Oct 2026 17:39:04 +0100 Subject: [PATCH] docs: mention querying durable state changes by slices Motivation: The durable state Persistence Query page says the query is only based on tags, but persistence-query also provides DurableStateStoreBySliceQuery with changesBySlices and currentChangesBySlices. Modification: Describe both ways of querying durable state changes: by tag with DurableStateStoreQuery, and by slices with DurableStateStoreBySliceQuery (marked @ApiMayChange), including what a slice is and the sliceForPersistenceId/sliceRanges helpers, and link to the EventsBySlice section. Note that support depends on the state store plugin. Result: Users know the by-slices query exists. Tests: - Not run - docs only References: None - found during a review of the docs --- .../main/paradox/durable-state/persistence-query.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/docs/src/main/paradox/durable-state/persistence-query.md b/docs/src/main/paradox/durable-state/persistence-query.md index 8a68ae63374..146837cbe98 100644 --- a/docs/src/main/paradox/durable-state/persistence-query.md +++ b/docs/src/main/paradox/durable-state/persistence-query.md @@ -35,7 +35,18 @@ durable state is stored in a database and fetched as an asynchronous stream to t durable state, provided by the `DurableStateStoreQuery` interface, is used to implement tag based searches in Pekko Projections. -At present the query is based on _tags_. So if you have not tagged your objects, this query cannot be used. +Changes to durable state can be queried in two ways, depending on which queries the state store plugin implements: + +* by _tag_, with `changes` and `currentChanges` of @apidoc[pekko.persistence.query.*.DurableStateStoreQuery]. + If you have not tagged your objects, this query cannot be used. +* by _slices_, with `changesBySlices` and `currentChangesBySlices` of @apidoc[pekko.persistence.query.typed.*.DurableStateStoreBySliceQuery] + for a given entity type and slice range. A slice is deterministically defined based on the persistence id, and the + purpose is to evenly distribute all persistence ids over the slices. `sliceForPersistenceId` returns the slice of a + persistence id and `sliceRanges` splits all slices into a given number of ranges, for example to run one query per range. + This is similar to @ref:[EventsBySlice](../persistence-query.md#eventsbyslice-and-currenteventsbyslice) for event + sourced entities. This API may change. + +Refer to the documentation of the state store plugin you are using for which of these queries it supports. The example below shows how to get the `DurableStateStoreQuery` from the `DurableStateStoreRegistry` extension.