Snapshots

A snapshot is a point-in-time, internally consistent view of every Permission Set Materialize is tracking, computed at a specific SpiceDB revision. Every piece of permission data Materialize hands you is anchored to the revision (ZedToken) it was computed at — that revision is the snapshot’s identity.

Snapshots are what make the two Materialize APIs compose safely:

• The initial backfill reads a snapshot in full.
• WatchPermissionSets advances that snapshot forward, delivering the deltas that move it from one revision to the next.

Why the revision matters

Because each event carries its revision, your consumer can always answer “as of when is my local data correct?” and resume from exactly the right place after a crash or disconnect. Storing the snapshot revision in the same transaction as the permission data it describes is the core durability guarantee: whatever revision you restart from, no events are skipped and no inconsistent state is observable.

Snapshot lifecycle events

• Revision checkpoint — SpiceDB changed, but nothing Materialize watches was affected. Advance your stored revision so you know where to resume.
• Breaking schema change — the current snapshot is invalidated; you must build a fresh snapshot by re-running the backfill at the new revision.
• Snapshot rotation — Materialize periodically deploys a new internal snapshot of the origin SpiceDB system as part of routine maintenance. A request against a retired snapshot returns Aborted: Requested Revision Is No Longer Available, signalling the consumer to re-run the backfill from scratch.