Query Language

Query which resources users have access to in your application.

The Query Language is a declarative, SQL-like language used to query WorkOS FGA for (1) the set of resources a particular subject has access to or (2) the set of subjects who have access to a particular resource. Examples of queries that can be specified with the query language include:

List all documents user:A is a viewer on.

List all users who are editors of document:finance-report.

List all resources user:malicious has access to.

List all users who have the permission view-financial-reporting.

and many more

Overview

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

Select Clause

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

Select Resources

Return resources a subject has access to

 select <resource_types>

<resource_types> can be a comma separated list of one or more resource types that results of the query will be filtered to. To select resources matching any resource type, pass a wildcard (*) instead.

Select Subjects

Return subjects that have access to a resource.

 select <relations> of type <subject_types>

<relations> and <subject_types> can be comma separated lists of one or more relations or one or more resource types respectively, that results of the query will be filtered to. To match any relation or any subject type, pass a wildcard (*) for the <relations> or <subject_types> properties respectively.

Where Clause

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>

<subject> must be a resource in the format <resource_type>:<resource_id>. <relations> can be a comma separated list of one or more relations. To match any relation, pass a wildcard (*) instead.

For Clause

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>

<relations> and <subject_types> can be comma separated lists of one or more relations or one or more resource types respectively. To match any relation or any resource type respectively, pass a wildcard (*) instead.

Implicit vs. Explicit Results

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 relation inheritance. Without the explicit keyword specified, a query will return both explicit and implicit results.

Example: Get all users who explicitly have the viewer relation on document:doc1

 select explicit viewer of type user for document:doc1

Example: Get all users who have the viewer relation on document:doc1 explicitly OR implicitly

 select viewer of type user for document:doc1

Examples

Get all documents on which user:1 is a viewer (either explicitly or implicitly)

 select document where user:1 is viewer

Get all documents on which user:1 is explicitly a viewer

 select explicit document where user:1 is viewer

Get all documents on which user:1 has any relation (either explicitly or implicitly)

 select document where user:1 is *

Get all resources of any type on which user:1 has any relation (either explicitly or implicitly)

 select * where user:1 is *

Get all users who are viewers of document:doc1 (either explicitly or implicitly)

 select viewer of type user for document:doc1

Get all users who are explicitly viewers of document:doc1

 select explicit viewer of type user for document:doc1

Get all users who have any relation on document:doc1 (either explicitly or implicitly)

 select * of type user for document:doc1

Get all subjects of any type who have any relation on document:doc1 (either explicitly or implicitly)

 select * of type * for document:doc1

Warrant TokensConfigure whether you favor performance or consistency on a per request basis depending on your application's consistency requirements

Up next