> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fga.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Permissions Index Terminology

> Learn the core terminology behind the Permissions Index.

## Search With Permissions

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

Learn more in [Search With Permissions](https://docs.fga.dev/integration/advanced/search-with-permissions.md).

## 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:

FGA model · DSL

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](https://docs.fga.dev/permissions-index/best-practices.md#evaluating-freshness-on-every-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.