Snapshots and history
A document keeps every change it applied. That history is what lets it merge, undo and travel back in time, and it grows with every edit. A snapshot is the state of every handler at one version: the changes it covers can then be pruned.
final snapshot = doc.takeSnapshot(); // and prune what it covers
final checkpoint = doc.takeSnapshot(pruneHistory: false); // keep the history
other.importSnapshot(snapshot);
Take, import, merge
- Take.
takeSnapshot()captures the state at the current version. - Import.
importSnapshot(snapshot)replaces the base of the document when the snapshot is newer or equal. It returnsfalse, and changes nothing, when the snapshot is older or concurrent. - Merge.
mergeSnapshot(snapshot)also takes an older snapshot. It throws aConcurrentSnapshotExceptionwhen the two cannot be merged. - With the changes after it.
import(snapshot:, changes:)takes a snapshot and the changes that follow it, in one call. - Prune later.
garbageCollectprunes the changes the last snapshot covers, up to a version every peer has seen.
A snapshot carries its versionVector, so peers can tell what it covers.
What a prune costs
A snapshot keeps the state, not the history. After a prune:
- the undo stacks are dropped;
- the history starts from the snapshot;
- a peer that has not seen the pruned changes gets the whole snapshot instead of the changes it misses.
Importing a snapshot prunes too. takeSnapshot, importSnapshot,
mergeSnapshot and import all prune by default. Pass pruneHistory: false
to keep the local history, for example to keep the undo stacks after a peer
sends a snapshot.
So prune when the history is no longer needed: pruneHistory: false takes a
checkpoint and keeps everything. The persistence adapters never prune on their
own (see Growth),
and the sync layer chooses the moment for you (see
Broadcasting a compaction
and Log compaction).
The document in the past
toTimeTravel() returns a read-only copy of the document with a cursor you move
through its changes. See History.
What a snapshot holds, and the rules of a merge, are in Snapshots.