Snapshots

A permission set 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 permission set snapshot’s identity.

A permission set snapshot is not the same thing as a SpiceDB snapshot of your schema and relationship data. A SpiceDB revision is a point-in-time coordinate encoded in a ZedToken, and a SpiceDB snapshot is the consistent read of your schema and relationship data as of that revision. A permission set snapshot is a further step removed: it’s what Materialize has computed from that SpiceDB snapshot, every permission set, as of the same revision. Internally, AuthZed engineers sometimes call this a groupstore. On this page, “snapshot” always refers to the permission set snapshot unless stated otherwise.

Permission set snapshots underpin both Materialize features: they’re what Materialize hydrates in order to answer Accelerated Queries, and they’re what make the Event Streams APIs compose safely:

• Materialize reads the current permission set snapshot directly to answer Accelerated Queries like CheckPermission, CheckBulkPermissions, LookupResources, and LookupSubjects.
• The initial backfill reads a permission set snapshot in full.
• WatchPermissionSets advances that permission set 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 permission set snapshot is invalidated. You must build a fresh one by re-running the backfill at the new revision.
• Snapshot rotation: as part of routine maintenance, Materialize periodically takes a new SpiceDB snapshot of your schema and relationship data and rebuilds the permission set snapshot from it. A request against a retired permission set snapshot returns Aborted: Requested Revision Is No Longer Available, signalling the consumer to re-run the backfill from scratch.