Skip to content
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.

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

rewrite intro to materialize #335

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open
Changes from all commits
Commits
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
47 changes: 22 additions & 25 deletions pages/authzed/concepts/authzed-materialize.mdx
Original file line number Diff line number Diff line change
@@ -1,45 +1,42 @@
import { Callout } from 'nextra/components'

# AuthZed Materialize (Early Access)

AuthZed Materialize works with AuthZed Dedicated and is inspired by the Leopard index component described in the [Zanzibar paper](https://zanzibar.tech/2IoYDUFMAE:0:T).
Much like the concept of a materialized view in relational databases, AuthZed Materialize supports SpiceDB permissions systems by precomputing permissions defined in your schema.

By creating a materialized view of your permissions in a relational database, you can efficiently sort, search, and filter massive lists of authorized objects while leveraging the authorization computation capabilities of SpiceDB.
# AuthZed Materialize

<Callout type="info">
AuthZed Materialize is available to users of AuthZed [Dedicated] as part of an early access program.
Don't hesitate to get in touch with your AuthZed account team if you would like to participate.
</Callout>

[Dedicated]: ../guides/picking-a-product#dedicated

## What Is AuthZed Materialize?
AuthZed Materialize is inspired by the Leopard index component described in the [Zanzibar paper](https://zanzibar.tech/2IoYDUFMAE:0:T).
Much like the concept of a materialized view in relational databases, AuthZed Materialize is a service that computes how permissions change after relationships
are written, when those relationships affect a subject's membership in a permission set or a set’s permission on a specific resource.
These permissions are then streamed to your client, so that you can store them as a denormalized table, and then do operations like searching, sorting, and filtering much more efficiently.

Materialize streams computed permission updates to a client.
Updates occur after a relationship is written that affects a subject's membership in a permission set or a set’s permission on a specific resource.
The intent is for users to process these updates and store them to form a precomputed and denormalized view of SpiceDB permissions.
AuthZed Materialize allows you to:

## When To Use AuthZed Materialize?
- speed up `CheckPermission` and `CheckBulkPermissions`
- speed up `LookupResources` and `LookupSubjects`, especially when there is a large number of resources
- build authorization-aware UIs, e.g. by providing a filtered and/or sorted list of more than several thousand authorized objects
- perform ACL filtering in other secondary indexes, like a search index (e.g. ElasticSearch)

If you need to provide a filtered and/or sorted list of more than several thousand authorized objects or if you need an authorization-aware search index, you probably need Materialize.

The primary use case for Materialize is to denormalize computed permissions into systems that excel at data retrieval operations like searching, sorting, and filtering.
[Dedicated]: ../guides/picking-a-product#dedicated

There are some authorized object listing scenarios where [LookupResources] or [LookupSubjects], without Materialize, can return a response without a large computational cost.
Those scenarios include:
## Limitations

1. Paginating through a list of authorized objects without sorting or filtering ([LookupResources] supports cursor-based pagination, but the list of objects is returned in a non-deterministic order)
2. Listing a small set (in the realm of thousands) of ordered or filtered objects.
If there are:

If you do make a [LookupResources] or [LookupSubjects] request with a significant computational cost, you can expect the request to be slow and to use a large number of system resources, leading to slower response times for other queries.
- [Caveats]
- [Wildcard] subject types
- [.all]

## Current Limitations
on the path of permissions computed by Materialize, it will error out.
However, your schema can still include them.

- [Caveats](https://authzed.com/docs/spicedb/concepts/caveats) are not supported on the path of permissions computed by Materialize
- [Wildcard](https://authzed.com/docs/spicedb/concepts/schema\#wildcards) subject types are not supported on the path of permissions computed by Materialize
[Caveats]: https://authzed.com/docs/spicedb/concepts/caveats
[Wildcard]: https://authzed.com/docs/spicedb/concepts/schema\#wildcards
[.all]: https://authzed.com/docs/spicedb/concepts/schema\#all-intersection-arrow

You can still use both Caveats and Wildcards, so long they are not part of the path to the permissions you've asked Materialize to query.
[Dedicated]: ../guides/picking-a-product#dedicated

## Client SDK