This is an automated email from the ASF dual-hosted git repository.
pjfanning pushed a commit to branch main
in repository
https://gitbox.apache.org/repos/asf/pekko-persistence-cassandra.git
The following commit(s) were added to refs/heads/main by this push:
new 2a83887 document the Cassandra driver page size (#489)
2a83887 is described below
commit 2a83887d4d26314ecc07fe6def46aa941ed39b08
Author: PJ Fanning <[email protected]>
AuthorDate: Mon Aug 24 10:45:30 2026 +0100
document the Cassandra driver page size (#489)
Motivation:
The driver's page size is the setting that controls how many rows a query
retrieves per round-trip, and it is the correct lever for tuning reads
that return many rows. It was not mentioned anywhere in the documentation,
which makes it easy to reach for a CQL `LIMIT` instead. A `LIMIT` caps the
total rows a query returns and would silently truncate results rather than
page them.
Modification:
Add a "Page size" subsection under "Cassandra driver configuration" in
docs/configuration.md covering the driver default of 5000, how to set it
globally, and how to set it per execution profile. Both profiles the
plugin uses are named: `pekko-persistence-cassandra-profile` for the
journal and query parts, `pekko-persistence-cassandra-snapshot-profile`
for the snapshot store.
The section also states what the setting does not do: it bounds the rows
in flight per round-trip, not the total an operation retains, so it does
not by itself cap the memory of a query whose whole result is collected
before it is acted on.
Result:
The page size is discoverable from the configuration documentation, with
the correct profile names and without overstating what it bounds.
Tests:
- Not run - docs only
- sbt docs/paradox - builds, section renders and existing extref links
resolve
References:
None - documents an existing Cassandra driver setting
---
docs/src/main/paradox/configuration.md | 32 ++++++++++++++++++++++++++++++++
1 file changed, 32 insertions(+)
diff --git a/docs/src/main/paradox/configuration.md
b/docs/src/main/paradox/configuration.md
index 10799a7..6ee93df 100644
--- a/docs/src/main/paradox/configuration.md
+++ b/docs/src/main/paradox/configuration.md
@@ -37,6 +37,38 @@ If the ip addresses of your cassandra nodes might change
(e.g. if you use k8s) t
should also be set (resolves a dns address again when new connections are
created). This also implies disabling java's dns cache with
`-Dnetworkaddress.cache.ttl=0`.
+### Page size
+
+The page size controls how many rows the driver retrieves per network
round-trip. Queries that can return many
+rows are fetched a page at a time, and the driver requests the next page
automatically as the results are
+consumed, so this is a matter of how the reads are chunked rather than how
many rows an operation returns.
+
+The driver default is 5000 rows. To change it for every query:
+
+```
+datastax-java-driver.basic.request.page-size = 1000
+```
+
+The plugin issues its queries under two execution profiles, so the page size
can also be set for one of them on
+its own. The journal and query parts use
`pekko-persistence-cassandra-profile`, the snapshot store uses
+`pekko-persistence-cassandra-snapshot-profile`:
+
+```
+datastax-java-driver.profiles {
+ pekko-persistence-cassandra-profile {
+ basic.request.page-size = 1000
+ }
+ pekko-persistence-cassandra-snapshot-profile {
+ basic.request.page-size = 100
+ }
+}
+```
+
+A smaller page size lowers the number of rows held per round-trip and the
amount of work in a single Cassandra
+read; a larger one reduces the number of round-trips needed to read a large
result set. It bounds the rows in
+flight, not the total an operation retains, so it does not by itself cap the
memory used by a query whose whole
+result is collected before it is acted on.
+
### Cassandra driver overrides
@@snip [reference.conf](/core/src/main/resources/reference.conf) { #profile }
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
