Hydration
Draft — content review needed. This concept page was promoted from prose that previously lived inline in the API reference. The mechanics below are accurate to the existing docs; the framing is new and should be reviewed (and expanded with diagrams/examples) before publishing.
Hydration is the process of populating your application’s local copy of permission data for the first time — the initial backfill that gets you from an empty index to a complete, queryable Permission Sets store.
When you first bring a system online, you have no permission data locally. Hydration reads the current state of every permission set Materialize is configured to watch, using LookupPermissionSets, and writes it into your datastore. Once hydration is complete, you switch to WatchPermissionSets to keep that data current — see Snapshots for how the handoff stays consistent.
The hydration lifecycle
- Backfill — call LookupPermissionSets, paging through the stream via cursors until an iteration yields zero events. Each event carries the permission-set data to store and the cursor to resume from on failure.
- Record the snapshot revision — every backfill event includes the revision (
ZedToken) the data was computed at. Store it transactionally alongside the data. - Switch to the change stream — once the backfill completes, open WatchPermissionSets using the stored snapshot revision so no changes are missed between hydration and live updates.
Hydration is not only a first-run concern. You must re-hydrate after a breaking schema change, which renders previously indexed permission sets stale. Build the machinery to re-run hydration at any time. See Managing Client State.
Hydration and snapshots
Hydration always produces a snapshot — a point-in-time, internally consistent view of the permission sets at a specific revision. The relationship is one-directional: hydration is the act; a snapshot is the result. You hydrate to a snapshot revision, then keep that snapshot live with the change stream.
TODO (Sam): expand with a concrete worked example and the four-phase / blue-green re-hydration strategy for breaking schema changes, currently documented under LookupPermissionSets.