R2D1 / 文档

核心概念

R2D1 是一个协调两个存储 contract 的 framework-independent Java library。DocumentStore 是完整文档和逻辑存在性的权威来源，IndexStore 是用于查询的可重建 projection。

R2D1

分离这两个角色后，可以用同一个 collection API 组合 R2 + D1、R2 + JDBC、Filesystem + D1 或 Filesystem + JDBC。组合改变时，@Document、@Id、@Index 以及 mutation/query 流程不变。

@Document 指定 document type 的 collection 名称。使用一个非空 String member 上的 @Id 作为标识，只有 @Index 字段会投影到 index store。

R2D1 不选择 JSON library。DocumentCodec 负责 domain object 与 authoritative store 保存的 StoredDocument bytes 之间的边界。

@Document("users")
public record User(
    @Id String id,
    @Index String country,
    @Index long score,
    String name) {}

DocumentStore 通过异步 SPI 提供 serialized document 的 list、put、get、delete。R2 和 filesystem 实现是 document store，不是 query engine。

get(id) 直接读取 document store。即使 index row 仍然存在，没有 authoritative document 时该文档也不具有逻辑存在性。

IndexStore 将 document key 和 @Index 字段值保存为一条 projection。D1 和 JDBC 实现这个 contract。

索引可以丢弃并重建。rebuildIndex() 扫描 authoritative document 并替换 collection 的 derived rows。这个操作不是原子的，应在暂停 collection 写入时执行。

R2D1Collection.query() 返回 immutable query builder。过滤只能使用显式索引字段，多项比较使用 AND 组合。

可以使用一个 indexed sort、正数 limit 以及上一页的不透明 cursor。cursor 由 adapter 创建，不要解析或修改它。