Skip to content

add section on event ordering for materialize #403

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

add section on event ordering for materialize #403

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions pages/authzed/concepts/authzed-materialize.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -426,6 +426,17 @@ To determine if a schema change is breaking, we provide the `materialize-cli` to
`materialize-cli` is still in early development, please reach out to us if you want to try it as part of AuthZed Materialize early access.
</Callout>

### Event Ordering and Delivery Guarantees

- **Ordered by revision (and usually timestamp)**
Events emitted by Materialize follow the same revision order as the SpiceDB Watch API. This order reflects the sequence of committed transactions. In most cases, events also follow timestamp order, although this is datastore-dependent. For example, Postgres may not preserve strict timestamp ordering due to concurrency behavior.

- **Revisions are delivered in order**
Materialize guarantees at-least-once delivery and preserves the order of revisions exactly as emitted by SpiceDB. Revisions will not arrive out of order. However, events within a single revision may appear in any order, since their intra-revision ordering is not semantically significant.

- **"Revision completed" indicates prior events have been received**
All events for a given revision will be emitted before the corresponding `"revision completed"` event is sent. If strict ordering of events within a revision is required, client-side ordering logic must be implemented.
Copy link
Contributor

@vroldanbet vroldanbet Oct 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ordering of events of a revision is semantically irrelevant, I think that was made clear in the previous point, so it seems confusing to mention that the client should take care of this


#### Errors

##### FailedPrecondition: Revision Does Not Exist
Expand Down
Loading