Skip to content

DOC-6827 Add Lettuce probabilistic data type examples and rundown page - #3610

Merged
andy-stark-redis merged 5 commits into
mainfrom
DOC-6827-prepare-lettuce-probabilistic-data-type-docs
Sep 10, 2026
Merged

DOC-6827 Add Lettuce probabilistic data type examples and rundown page#3610
andy-stark-redis merged 5 commits into
mainfrom
DOC-6827-prepare-lettuce-probabilistic-data-type-docs

Conversation

@andy-stark-redis

@andy-stark-redis andy-stark-redis commented Jul 10, 2026

Copy link
Copy Markdown
Contributor

Summary

Adds Lettuce (Java) coverage for the probabilistic data types, in two parts.
Documentation only — 15 files, all additions.

Examples

Staged Lettuce async + reactive doctests under
local_examples/<set>/lettuce-async|lettuce-reactive/:

Set Data-type page
bf_tutorial Bloom filter
cuckoo_tutorial Cuckoo filter
cms_tutorial Count-min sketch
topk_tutorial Top-K
tdigest_tutorial t-digest
hll_tutorial HyperLogLog
home_prob_dts combined rundown / landing

The per-type data-type pages embed clients-example without a lang_filter, so the
new Java-Async and Java-Reactive tabs appear automatically once the example
pipeline regenerates examples.jsonno edits to those pages are needed, and none
are in this PR.
Confirmed in a local build: all six probabilistic data-type pages
pick up both tabs.

Rundown page

New content/develop/clients/lettuce/prob.md, adapted from the Jedis page, with
lang_filter="Java-Async,Java-Reactive".

Requirements

The probabilistic commands need Lettuce 7.7.0 or later (released 2026-08-18), which
is the first release carrying Bloom, Cuckoo, CMS, t-digest, Top-K and HLL support. It is
still the current release.

In line with the Jedis, redis-py, Go and Node.js probabilistic pages — none of which
state a client version requirement — prob.md carries no version banner.

Verification

Not inspection-only; the examples were compiled and run:

  • All 14 files compile against lettuce-core 7.7.0.RELEASE.
  • All 14 pass against a live Redis 8.10.1, through the repo's own harness
    (./run.sh <set> lettuce-async lettuce-reactive) as well as directly.
  • 140 of 140 >>> expected-output comments were mechanically diffed against
    observed stdout, rather than spot-checked. All match.
  • Top-K eviction order, the one non-obvious output, was confirmed stable across
    repeated fresh runs.
  • Hugo builds clean, with no new warnings and none naming a probabilistic set.

Re-verified after merging main on 2026-09-10, against a newer server (8.10.1) than
the examples were originally written and checked against.

Notes for review

Two things worth a look, both of which only surfaced once the examples could actually
be executed:

  • t-digest values are double, not String. tdigestAdd, tdigestRank and
    tdigestCDF take a double value parameter, so the numeric arguments are unquoted.
  • The reactive Top-K tabs show a Value wrapper, and the async ones show null.
    This asymmetry is deliberate in Lettuce, not an inconsistency in the docs: reactive
    returns Flux<Value<String>> while async returns RedisFuture<List<String>>,
    because a Flux cannot emit null whereas a List can hold it. So the reactive tab
    prints Value.empty / Value[handlebars] where the async tab prints null /
    handlebars.

Not covered

tdigestByRevRank, tdigestRevRank, tdigestTrimmedMean, tdigestInfo,
cmsInitByDim and cmsMerge exist in 7.7.0 but are not exercised by these examples —
possible future coverage, not a gap in what is documented here.


Note

Low Risk
Documentation and example/test assets only; any harness dependency bump mainly affects CI compile of Lettuce examples, not production runtime.

Overview
Adds Lettuce client documentation for Redis probabilistic data types via new content/develop/clients/lettuce/prob.md, mirroring other clients’ rundown pages and wiring clients-example snippets for Java-Async and Java-Reactive (home_prob_dts steps: Bloom, Cuckoo, HyperLogLog, CMS, t-digest, Top-K).

Introduces 14 doctest-style examples under local_examples/ (async + reactive for bf_tutorial, cuckoo_tutorial, cms_tutorial, hll_tutorial, tdigest_tutorial, topk_tutorial, and the combined home_prob_dts set), so existing probabilistic data-type pages can pick up Lettuce tabs once examples.json is regenerated.

Per the PR notes, the example harness is intended to use lettuce-core 7.7.0+ for these probabilistic APIs (that pin may land with or alongside this docs work).

Reviewed by Cursor Bugbot for commit 4af834c. Bugbot is set up for automated code reviews on this repo. Configure here.

Stage Lettuce async + reactive doctests for the bloom, cuckoo, CMS, top-k,
t-digest and HLL tutorial sets plus the combined home_prob_dts set, and add the
client-specific rundown page at content/develop/clients/lettuce/prob.md.

This is preemptive work: probabilistic command support is not in a released
lettuce-core yet, so the examples are written against the Lettuce feature PRs
(BF/CF/top-k merged to main; CMS and t-digest still open on the Dgramada fork,
so their signatures may still shift). A Codex review flagged every non-HLL call
as an unknown method - that is expected against the repo's pinned released jar,
not a defect. Multi-step sets (t-digest, home_prob_dts) are authored as
self-contained per-STEP blocks rather than one method chain threaded through the
STEP markers, because the clients-example shortcode extracts each step by line
range and a threaded chain renders as broken mid-chain fragments.

Learned: multi-step doctests must be self-contained per STEP block or the shortcode extracts broken mid-chain fragments
Constraint: each STEP_START/STEP_END block must stand alone (its own async chain, or per-statement reactive blocks), never span a single threaded method chain
Rejected: one async/reactive chain threaded through all STEP markers | shortcode extracts per-step line ranges, so a threaded chain yields uncompilable fragments
Recheck: when Lettuce CMS (redis/lettuce#3821) and t-digest (#3823) merge and release - re-pin lettuce-core, re-run the doctest harness so the REMOVE-block asserts become real oracles, and re-diff the CMS/t-digest signatures
Ticket: DOC-6827
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@github-actions

github-actions Bot commented Jul 10, 2026

Copy link
Copy Markdown
Contributor

DOC-6827

@github-actions

Copy link
Copy Markdown
Contributor

@andy-stark-redis andy-stark-redis self-assigned this Jul 10, 2026
@andy-stark-redis andy-stark-redis added the parked PR speculatively added based on pre-release info. Check validity when release goes ahead. label Jul 10, 2026
Lettuce 7.7.0.RELEASE (2026-08-18) ships all six probabilistic families,
so the park trigger fired and the examples could finally be compiled and
run rather than reasoned about. Three defects surfaced that five rounds
of signature analysis had all passed as clean.

t-digest took `double`, not `V`. 32 compile errors across the four
t-digest-touching files: `tdigestAdd`, `tdigestRank` and `tdigestCDF`
declare `(K, double...)`, and the examples passed quoted strings
("45.88", "50"). Every park-time note checked method name, arity and
return type — never the parameter type — and `(K, V...)` vs
`(K, double...)` are identical on all three. The 08-10 note's own
shorthand `tdigestAdd(k, v)` encoded the wrong assumption and it was
carried forward through four re-verifications. Fixed by unquoting 68
numeric literals, scoped to the t-digest call spans so the BF/CF/CMS
sibling calls in the same files kept their string values.

Reactor forbids a null from map(). The two reactive examples did
`.map(v -> v.getValueOrElse(null))` on Top-K replies, which throws
NullPointerException at runtime — so those files had never once been
executed. Lettuce returns `Flux<Value<String>>` reactively but
`RedisFuture<List<String>>` async, precisely because a Flux cannot carry
null while a List can. The examples had copied the async expected output
and forced nulls through a mapper to match it. Dropping the mapper lets
the real `Value.empty` / `Value[handlebars]` shape surface, which is the
honest reactive idiom rather than a fiction that matches the async tab.

One expected output was simply wrong, in the async file too. Top-K
eviction for home_prob_dts printed
[null, null, null, Rock me, Handel, Only one more time, null] — two
evictions at positions 4 and 5 — where the comment claimed five nulls
then a single "Rock me, Handel". It survived because that println had no
assertion at all; the reactive Top-K one had only a .size() check. Added
content assertions at all three sites so the >>> values are now guarded,
and verified the eviction order is stable across three fresh runs before
baking it in.

Verified: all 14 compile against 7.7.0 and all 14 pass against Redis
8.8.0, with 132 of 132 expected-output comments matching observed stdout
(mechanically diffed, not spot-checked). Negative control run: perturbing
one new assertion does fail the build.

Learned: a tripwire guarding a false conclusion preserves the falsehood
perfectly — all four pinned blob SHAs matched at the release tag, which
correctly proved nothing had moved and told us nothing about whether the
claim was ever true.

Recheck: prob.md needed no edit — no bannerText, no version-gating prose.
Recheck: 7.7.0 has neither the reactive() deprecation nor the
  commands(factory) replacement, though #3731's diff read "@deprecated
  since 7.7"; #3781 landed and was reworked away before the tag. Do not
  document commands(factory) as a migration path yet.
Gaps: tdigestByRevRank, tdigestRevRank, tdigestTrimmedMean, tdigestInfo,
  cmsInitByDim and cmsMerge remain uncovered by these examples.
The harness pinned lettuce-core 6.5.5.RELEASE, which cannot compile the
repo's own Lettuce examples: the same 43 non-DJL example files give 200
compile errors at 6.5.5 and 0 at 7.7.0. Only 104 of those errors are this
PR's probabilistic files — the other 96 are pre-existing arrays, JSON and
query examples that had already outgrown the pin. So this is a fix to a
stale pin, not a bump taken for this PR's convenience.

Verified through the real harness rather than a throwaway project: all 7
probabilistic sets pass in both async and reactive, and so do cmds_hash
(incl. sync), set_and_get, cmds_string, cmds_sorted_set, cmds_generic and
arrays_tutorial. Nothing regressed.

Learned: run.sh:407 seeds a toolchain pom with
`[ -f "$d/pom.xml" ] || cp ...`, so editing a tracked pom-*.xml has no
effect while a cached work/<client>/pom.xml exists. The first run after
this bump reported FAIL with every tdigest method "cannot find symbol" —
which reads exactly like a missing-API problem rather than a stale
toolchain, and my throwaway maven project had already passed on the same
sources, which is what exposed the contradiction. Delete
work/<client>/pom.xml after changing a client version.

Recheck: the four DJL-dependent vec examples (HomeQueryVecExample,
  HomeVecSetsExample) cannot compile under any harness pom — none carries
  ai.djl.* — so they are outside this verification either way, not a
  regression from the bump.
@github-actions

github-actions Bot commented Aug 25, 2026

Copy link
Copy Markdown
Contributor

🧠 Redis Memory

Found 8 related items from repository history (3 new this commit):

Memory updated at 4af834c

@andy-stark-redis andy-stark-redis removed do not merge yet parked PR speculatively added based on pre-release info. Check validity when release goes ahead. labels Aug 25, 2026
@andy-stark-redis andy-stark-redis changed the title DOC-6827 Prepare Lettuce probabilistic data type docs DOC-6827 Add Lettuce probabilistic data type examples and rundown page Aug 25, 2026
@andy-stark-redis
andy-stark-redis requested a review from a team August 25, 2026 10:24
@andy-stark-redis andy-stark-redis added the clients Client library docs label Aug 25, 2026

@dwdougherty dwdougherty left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM.

…uce-probabilistic-data-type-docs

# Conflicts:
#	build/example-test-harness/pom-lettuce-async.xml
#	build/example-test-harness/pom-lettuce-reactive.xml
@andy-stark-redis
andy-stark-redis merged commit f3c00ca into main Sep 10, 2026
96 checks passed
@andy-stark-redis
andy-stark-redis deleted the DOC-6827-prepare-lettuce-probabilistic-data-type-docs branch September 10, 2026 13:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

clients Client library docs

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants