Query Language

A query is composed of a select clause and either a for clause (if querying for subjects) or a where clause (if querying for resources):

select permission where user:tony-stark is member

The select clause specifies whether a query should return resources a subject has access to or return subjects that have access to a resource.

Return resources a subject has access to

select <resource_types>

Return subjects that have access to a resource.

select <relations> of type <subject_types>

When selecting resources (e.g. select tenant), provide a where clause to specify a subject and one or more relations that subject must have on any resources returned in the query result.

select <resource_types> where <subject> is <relations>

When selecting subjects (e.g. select member of type user), provide a for clause to specify a resource and one or more relations subjects must have on the specified resource to be returned in the query result.

select <relations> of type <subject_types> for <resource>

A query can optionally include the explicit keyword immediately following the select keyword to indicate that the query should only return results that explicitly match the provided relations. Explicit results are results for which a warrant matching one or more of the relations specified in the query explicitly exists. Implicit results are results which may implicitly match the relations specified in the query through inheritance rules. Without the explicit keyword specified, a query will return both explicit and implicit results.

select explicit viewer of type user for document:doc1

select viewer of type user for document:doc1

Schema policies are not supported in the current Query implementation. Any access results that are granted only by schema policies (as determined via the check endpoint) will be excluded from query responses.

This limitation exists because schema policies are fundamentally more complex than warrant policies. While warrant policies apply to specific relationships (e.g., user:1 is viewer of document:doc1), schema policies define rules that apply across all resources of a certain type and relation – for example, every viewer of every document.

This generalization introduces two core issues:

1. Scalable Evaluation: The query engine would have to evaluate every resource of type B for every relation A, leading to major performance bottlenecks at scale.
2. Security and UX Risks: Alternatively, returning wildcard-based access (e.g., “user has access to resource type B:*”) increases the risk of unintended data exposure and shifts the burden of filtering valid results to the application layer.

Given these challenges, schema policies should be evaluated like traditional policy engines – by explicitly checking access between individual subjects and resources. This is what the check endpoint is for.

To check access to a list of resources when using schema policies, you have two options:

1. Convert schema policies into equivalent warrant policies where feasible.
2. Use the batch check endpoint to validate access for many resources individually.

The query engine does not support join semantics across relationships. For example, a query like:

select viewer of type user for document:doc1 where group is viewer

…is not supported directly.

To achieve a similar behavior, you could do one of the following:

1. (Recommended) Define a new relation in your schema that does the join via inheritance rules

type user

type group
  relation member [user]

type document
  relation viewer [user, group]
  relation group_viewer []

  // Query for documents where a user is a viewer through their group membership
  inherit group_viewer if
    relation member on viewer [group]

  inherit viewer if
    relation member on viewer [group]

Then you can query for the new relation:

select group_viewer of type user for document:doc1

If you want to intersect results of two queries, you can use an all_of rule in your schema to define a new relation that combines the results of two existing relations. For example:

type document
  relation subscriber [user]
  relation owner [group]

  inherit subscriber_and_owner if
    all_of
       relation owner
       relation subscriber

  inherit owner if
    relation member on owner [group]

Then you can query for the new relation:

select subscriber_and_owner of type user for document:doc1

2. Chain queries and combine results in application logic

select viewer of type group for document:doc1
select member of type user for group:xyz // using groups from prior query

3. Use a batch check to check access on multiple resources returned by a query

select viewer of type group for document:doc1

Then you can batch check user:xyz on all viewer groups for document:doc1.