Permissions Index Terminology

Search With Permissions

"Given a particular search filter and sort order, what objects can the user access?"

Learn more in Search With Permissions.

Permissions Index

A fully flattened set of permissions containing every possible combination of "who can do what to which object" as exactly defined by your authorization model.

Indexable Path

The subset of relations in an authorization model that matters for a given index. This "trimmed" model contains the indexed relation(s) and all other relations that influence it.

Understanding your indexable path is important for attaching new authorization models to an existing index. The new model is compatible only if its "indexable path" matches the one used to create the index. If the new model modifies the indexable path, the model is incompatible with the current index and requires a new index to be created.

For example, in a simple document management system like the one below:

type user

type folder
 relations
   define viewer: [user]

type document
 relations
   define folder: [folder]
   define viewer: [user]
   define can_view: viewer or viewer from folder
   define can_share: [user] or viewer

For an index covering the document#can_view relationship, the indexable path is:

1. document#can_view itself,
2. document#viewer,
3. document#folder, and
4. folder#viewer.

The relation document#can_share, however, is not part of the indexable path, as it doesn't participate in the document#can_view relationship, either directly or indirectly.

Expansions

Fully flattened subject-relation-object entries stored in the Permissions Index representing all implicit relationships in the authorization graph.

Expansion Events

Insert or delete events in the Read Expansions stream. A single permission grant or revoke can result in one or more expansion events. When a permission is granted, INSERT events are streamed; when a permission is revoked, DELETE events are streamed. Each event has a unique, replay-stable event.id for deduplication. Your consumer listens for these events and updates your colocated permissions index accordingly.

If folder:3 contains three documents under it, writing a permission tuple like user:alice viewer folder:3 results in three new expansion events:

• INSERT user:alice can_view document:3-1
• INSERT user:alice can_view document:3-2
• INSERT user:alice can_view document:3-3

Freshness

Also called "staleness," freshness describes how up-to-date an index is, measured in seconds as NOW() - as_fresh_as. A lower number means a more up-to-date index. Use freshness to track progress while an index is being built, and to decide whether the index is current enough to answer a given request. For example, "only use the index if it is as fresh as 5 minutes ago."

The Read Expansions stream reports freshness in two places: event.as_fresh_as on expansion events and freshness.as_fresh_as on freshness events. Consumers calculate freshness from the newest, non-null value received from either field.