PlusAuth Query Language Reference

PlusAuth provides its own CQL for querying over resources in an easy way. It will be referred as PQL (PlusAuth Query Language) in PlusAuth documentation.

Common features and characteristics of PQL are as following:

1. Consists one or more statements
2. Logical connector operators ( AND, OR )
3. Common operators ( =, !=, <, >, >=, >=, IN, ILIKE )
4. Supports nested properties ( profile.name, metadata.color, .etc)
5. Field grouping ( profile[given_name = "John" AND family_name = "Doe" ] )

Below, you can find more examples and detailed characteristics explanations of PQL.

Values

Booleans, numbers and null do not need any wrapping whereas all other values must be wrapped with double quotes. Example values:

null
true
false
1
0
-1
"string"
"sentence with space"

Common operators

You can check equality, greatness and matching value in a list of values. Here is a sample query for retrieving entities whose email is verified.

email_verified = true

For retrieving entities whose email is NOT verified, you can use not equal operator

email_verified != true

You can use greater than (>), less than (<), greater or equal (>=), less or equal (<=) operators in the same way.

Logical operators

In some cases you may need to have more than one condition to apply for retrieving your resources. You can use AND,OR for this purpose.

Let's retrieve entities which has email as [email protected] or which has email_verified field set to false. Here is the query:

email = "[email protected]" OR email_verified != true

You can also group statements. Just wrap your condition with parentheses. Here is an example:

(profile.given_name = "Jane" AND profile.family_name != "Doe") OR email_verified = true

Match value in a list of values

For checking value from a defined list of values PQL provides IN operator. You can provide list of values being separated by commas.

profile.given_name IN "John","Jane"

The query above will retrieve entities whose given name is either "John" or "Jane"

Pattern matching

ILIKE operator can be used for queries that are data based on pattern-matching techniques. Its result includes strings that are case-insensitive and follow the mentioned pattern.

An underscore (_) in pattern stands for (matches) any single character; a percent sign (%) matches any sequence of zero or more characters.

Some examples for a entity with name abc:

name ILIKE "abc"  --> true
name ILIKE "a%"  --> true
name ILIKE "_b_"  --> true
name ILIKE "ab"   --> false
name ILIKE "bc"   --> false

ILIKE pattern matching always covers the entire string. Therefore, if it's desired to match a sequence anywhere within a string, the pattern must start and end with a percent sign.

To match a literal underscore or percent sign without matching other characters, the respective character in pattern must be preceded by the escape character. The default escape character is the backslash (\) character.