RocheDB v0.5.0: Data Locality for RAG and LLM Retrieval

Ring Locality

RocheDB uses a ring as a semantic and structural placement unit. An application, import rule, or operator chooses a ring when writing data:

users/123/profile
users/123/orders
shops/1123/orders
docs/japan/support
tenant/acme/orders/2026

That ring is not only a directory-like label. It is a coordinate in the retrieval space. When a request already knows its natural locality, RocheDB can open that local region first instead of scanning unrelated records and filtering later.

roche put --ring=docs/japan --payload='{"title":"Refund guide","status":"draft"}' --codec=json
roche get --ring=docs/japan --filter='{"status":"draft"}' --selection='{ title }'

The important part is not the string syntax. The important part is that placement and retrieval scope are connected. Short version: a ring is both where data is placed and where retrieval can start.

Not Only Point Reads

Point reads are important, but many real applications need related data. For example, a user page may need profile data, orders, billing information, and support metadata. In a relational database, that often becomes joins. In a document database, it often becomes manual denormalization or multiple application-side reads.

RocheDB v0.5.0 adds a locality mechanism for this kind of shape: stellar locality. A stellar group is a read lens over nearby rings. It lets related rings be read together without pretending that all data must live in one document.

roche stellar attach --stellar=user-123 --ring=users/123/profile
roche stellar attach --stellar=user-123 --ring=users/123/orders
roche stellar attach --stellar=user-123 --ring=shops/1123/orders
roche get --stellar=user-123

The same stellar view can be narrowed:

roche get --stellar=user-123 --subring=orders --limit=20

This is not meant to replace every join. It is meant to cover a different pattern: When the application already knows that several rings are useful neighbors, make that locality available to the database.

Why This Is Different from a Secondary Index

A secondary index usually gives another path to find rows by a key. That is useful, but it can also fight the primary layout. The index finds the matching keys, then the database may still need to jump around to fetch the records themselves.

RocheDB's current approach is more conservative. Secondary access should guide the query back toward ring-local reads where possible. In v0.5.0, stellar locality is not a global secondary index. It is a locality lens over rings that are already meaningful to the application. That keeps the model simple:

• rings define local placement;
• stellar groups define related local regions;
• filters and projections narrow the result after the local scope is chosen.

roche get --stellar=user-123 --filter='{"status":"paid"}' --selection='{ title status }'

This is why RocheDB is not just "routing by path." The ring path is part of the query plan, and stellar locality lets related ring coordinates become a retrieval unit.

Physical Locality

Logical locality is not enough by itself. If the storage layer gradually becomes fragmented, the first clean benchmark does not mean much. Real workloads mutate, delete, backfill, and query from odd angles.

RocheDB v0.5.0 adds early physical locality visibility through WAL locality reporting:

roche locality

The goal is to make locality observable before building heavier compaction and layout optimization features. This is still early, but the direction is clear:

• show how records are grouped physically;
• make locality drift visible;
• provide a base for future compaction;
• avoid hiding layout problems until performance has already degraded.

There is also a locality layout demo: examples/locality_layout_demo.sh
And a stellar data model demo: examples/stellar_data_model_demo.sh

Write Patterns and Mutation

RocheDB should not assume that writes are always clean. Applications backfill data. Imports arrive in imperfect order. Some records are attached to related data later. Some records are detached later.

v0.5.0 adds attach/detach workflows for stellar locality:

roche stellar attach --stellar=user-123 --ring=users/123/orders
roche stellar detach --stellar=user-123 --ring=users/123/orders
roche stellar list --stellar=user-123

This makes the locality model adjustable without rewriting the whole dataset. The current implementation is intentionally modest. It focuses on making relationships explicit and testable first. Heavier compaction and automatic relocation are better handled after the behavior is observable.

Atomic Workflows

RocheDB v0.5.0 also adds embedded atomic batch helpers:

• atomic batch put;
• atomic batch update;
• atomic batch delete.

These are designed for application workflows where a group of related changes should either commit together or not commit at all.

There are also cooperative coordinate locks:

• ring locks;
• stellar locks;
• TTL-based lock expiry;
• release-on-exception helpers.

These locks are opt-in. Normal lightweight NoSQL reads and writes do not pay for them unless the application chooses to use them. The goal is not to turn RocheDB into a financial ledger. The goal is to support higher-integrity application workflows without losing the ring-first retrieval model.

What the Benchmarks Are Testing

The main RocheDB benchmark claim is not "always faster than every database." The narrower claim is: If locality is meaningful, RocheDB can reduce how much unrelated data must be read, held, ranked, transferred, or passed downstream.

The current benchmark documents include working-set, memory-pressure, RAG-oriented, PostgreSQL, and Redis comparison helpers. Some examples from the repository:

Working-set benchmark - With 100 rings and 10,000 documents, scanned records per query dropped from 10,000 to 100.

Memory-pressure benchmark - With 100 rings, 100,000 documents, and 512-byte payloads, estimated candidate memory per query dropped from 93.079 MiB to 0.931 MiB.

Synthetic RAG benchmark - Recall stayed at 1.000 while scanned records per query dropped from 8,000 to 1,000, and estimated tokens per query dropped from 3960 to 657.8.

These are local synthetic and generated benchmarks, not universal performance claims. The scripts are in the repository so the numbers can be reproduced, challenged, and improved.

What Is Still Open

There are still important layout questions to solve. The biggest ones are:

• preserving physical locality as data mutates;
• compaction behavior over time;
• backfill-heavy workloads;
• secondary access paths that do not fight the primary ring layout;
• dynamic cluster membership without unnecessary remapping;
• deeper real-world benchmarks.

The current v0.5.0 work does not pretend those are solved forever. It gives RocheDB clearer mechanisms for observing and testing them.

Why I Think This Direction Matters

Many systems already know their useful locality: tenant; user; region; product area; document topic; time window; prompt or context domain; game world entity; application workflow. Often that information is known by the application but not directly usable by the database as a retrieval primitive.

RocheDB tries to close that gap. It does not ask every workload to become a RocheDB workload. It is most interesting when the application can place data in meaningful local regions and then benefit from reading those regions directly.

That is the direction of v0.5.0: make locality explicit, observable, and useful enough that it can become part of the database design itself.

Repository: github.com/puffball1567/rochedb
Release: github.com/puffball1567/rochedb/releases/tag/v0.5.0