핵심 개념

R2D1

두 역할을 분리하면 R2 + D1, R2 + JDBC, Filesystem + D1, Filesystem + JDBC를 같은 collection API로 사용할 수 있습니다. 조합이 바뀌어도 @Document, @Id, @Index와 mutation/query 흐름은 바뀌지 않습니다.

문서와 collection

@Document가 document type의 collection 이름을 정합니다. 비어 있지 않은 String member 하나에 @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)는 document store를 직접 읽습니다. index row가 남아 있어도 authoritative document가 없으면 문서는 논리적으로 존재하지 않습니다.

IndexStore

IndexStore는 document key와 @Index 필드 값을 한 행의 projection으로 저장합니다. D1과 JDBC가 이 contract를 구현합니다.

인덱스는 disposable합니다. rebuildIndex()는 authoritative document를 스캔하고 collection의 derived rows를 교체합니다. 비원자적 작업이므로 collection 쓰기를 멈춘 상태에서 실행하세요.

쿼리와 cursor

R2D1Collection.query()는 immutable query builder를 반환합니다. 필터는 명시적으로 인덱싱한 필드에만 적용하며 여러 비교는 AND로 결합됩니다.

한 개의 indexed sort, 양수 limit, 이전 페이지의 opaque cursor를 사용할 수 있습니다. cursor는 adapter가 만든 값이므로 해석하거나 수정하지 마세요.

• 지원되는 비교: eq, notEq, gt, gte, lt, lte
• 지원하지 않는 기능: join, 임의 SQL, OR predicate, full-text search, 정규식, client-side filtering