Skip to main content

Warrant Query Language

The Warrant Query Language (WQL) is a declarative, SQL-like language used to query Warrant for a set of resources (e.g. documents, users, permissions, etc.) matching one or more access rule requirements. Some useful queries the language can express are:

  1. List all documents user:A is a viewer on.
  2. List all users who are editors of document:finance-report.
  3. List all resources user:malicious has access to.
  4. List all users who have the permission view-financial-reporting.
  5. and many more...

Syntax and Format​

A query is composed of a select clause and (optionally) either a for clause or a where clause (depending on the select clause):

select permission
where user:tony-stark is member

Select Clause​

The select clause specifies whether a query should return objects or subjects.

Selecting Objects​

To select objects, a select clause should be in the following format:

select <objectTypes>

Where <objectTypes> is a comma separated list of one or more object types that resulting objects must match. To select objects matching any object type, pass a wildcard (*) for <objectTypes>.

Selecting Subjects​

To select subjects, a select clause should be in the following format:

select <relations> of type <subjectTypes>

Where <relations> is a comma separated list of one or more relations that resulting subjects must possess either explicitly or implicitly (more on this below), and <subjectTypes> is a comma separated list of one or more object types that all resulting subjects must match. To match any relation or any subject type, pass a wildcard (*) for the <relations> or <subjectTypes> properties respectively.

Where Clause​

When selecting objects (e.g. select tenant), use a where clause to specify a <subject> (in the format <subjectType>:<subjectId>) and a comma separated list of one or more <relations> the <subject> must have on all of the resulting objects. To select objects on which <subject> has any relation, pass a wildcard (*) for <relations>.

select <objectTypes>
where <subject> is <relations>

For Clause​

When selecting subjects (e.g. select member of type user), use a for clause to specify an <object> (in the format <objectType>:<objectId>) on which all resulting subjects must have one or more of the <relations> specified in the select clause.

select <relations> of type <subjectTypes>
for <object>

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 explicitly matching any <relations> filters. Explicit results are results for which a warrant matching the <relations> filters in the query explicitly exists in Warrant. Implicit results are results which may implicitly match the query's <relations> filters through a combination of other warrants and inherited relations specified by an object type. 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 objects 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