基本概念

R2D1

この2つの役割を分けることで、R2 + D1、R2 + JDBC、Filesystem + D1、Filesystem + JDBC を同じ collection API で組み合わせられます。組み合わせが変わっても @Document、@Id、@Index と mutation/query の流れは変わりません。

ドキュメントとコレクション

@Document が document type の collection 名を決めます。空でない String member の1つに @Id を付けて識別子にし、@Index のフィールドだけを index store に projection します。

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

DocumentStore は serialized document の list、put、get、delete を非同期 SPI として提供します。R2 と filesystem の実装は document store であり、query engine ではありません。

get(id) はこの store を直接読みます。index row が残っていても authoritative document がなければ、ドキュメントは論理的には存在しません。

IndexStore

IndexStore は document key と @Index フィールド値を1つの projection として保存します。D1 と JDBC がこの contract を実装します。

インデックスは破棄して再構築できます。rebuildIndex() は authoritative document を走査し、collection の derived rows を置き換えます。非アトミックなので collection への書き込みを止めて実行してください。

クエリとカーソル

R2D1Collection.query() は immutable query builder を返します。フィルタは明示的にインデックス化したフィールドだけに適用し、複数の比較は AND で結合します。

1つの indexed sort、正の limit、前ページの opaque cursor を使えます。cursor は adapter が作成する値なので解釈や変更をしないでください。

• サポートする比較: eq、notEq、gt、gte、lt、lte
• 提供しない機能: join、任意 SQL、OR predicate、全文検索、正規表現、client-side filtering