(pekko) branch main updated: docs: mention querying durable state changes by slices (#3595)

[he...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

He-Pin pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pekko.git


The following commit(s) were added to refs/heads/main by this push:
     new 93b48ec6c0 docs: mention querying durable state changes by slices (#3595)
93b48ec6c0 is described below

commit 93b48ec6c047178956f0c3cc2c9d9eddc0935550
Author: PJ Fanning <pj...@users.noreply.github.com>
AuthorDate: Fri Oct 9 05:22:36 2026 +0100

    docs: mention querying durable state changes by slices (#3595)
    
    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
---
 docs/src/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 8a68ae6337..146837cbe9 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.
 


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@pekko.apache.org
For additional commands, e-mail: commits-help@pekko.apache.org