DocumentStore

A durable, ordered store of JSON documents keyed by byte string.

A commit is appended to a checksummed write-ahead log and then applied to an in-memory sorted table; when that table reaches StoreOptions.memtableMaxBytes it is sealed and a new log begins, and a background pass writes it out as an immutable sorted segment. Segments are merged downwards through levels as they accumulate. A read consults the memtables newest first, then level 0's segments newest first, then one segment per level below that — stopping at the first version it finds, including a tombstone, which is an answer rather than a reason to keep looking.

The guarantee. After any interruption, reopening the store yields exactly the acknowledged prefix of the commits: every commit whose write returned is present, no commit that had not returned is present, and nothing in between is missing. Under Durability.SYNC that holds across power loss; under Durability.BUFFERED it holds across process death and sync is what extends it to the machine.

Concurrency: one writer, many readers. Writes are serialised on an internal lock — the engine assumes a single writing thread, and the lock is there so that a mistaken second one gets contention rather than a corrupt log. Reads take no lock and may run on any number of threads while a write is in progress.

A batch is atomic to a reader as well as to recovery: the sequence a read is bounded by is published only once every operation in the batch is in the memtable, so one view of the store never shows part of a batch. The unit is the view, not the call — a run of separate get calls is a run of separate reads, each at whatever sequence the store had reached. Take a Snapshot to read several keys as one.

DocumentStore.open(Path.of("data")).use { store ->
    store.put(Key.of("user:1"), Variant.fromJson("""{"name":"ada"}"""))
    store.get(Key.of("user:1"))?.select("$.name")?.stringValue()   // "ada"

    store.snapshot().use { snapshot ->
        store.scan(from = Key.of("user:"), snapshot = snapshot).use { cursor ->
            while (cursor.next()) println(cursor.key)
        }
    }
}