RSQL is a query language for parametrized filtering of entries in RESTful APIs. It is used to define both filtering and sorting statements of supported queries. The following grammar specification is written in EBNF notation (ISO 14977).
RSQL expression is composed of one or more comparisons, related to each other using logical operators:
These two operators can be used to join different comparison filters and build more involved queries, which can be as complex as required. By default, the AND operator takes precedence (i.e., it is evaluated before any OR operators are). However, a parenthesized expression can be used to change the precedence, yielding whatever the contained expression yields. Here are some examples:
age=gt=10;age=lt=20: find all users older than 10 and younger than 20
age=lt=5,age=gt=30: find all users younger than 5 or older than 30
age=lt=20;(role="CEO",name="John"): find all users younger than 20 and whose role is
CEOor whose name is
Comparison is composed of a selector, an operator, and an argument.
comparison = [selector][comparison-operator][arguments]
The selector identifies an attribute of the catalog to filter by. It can be any non-empty Unicode string that does not contain reserved characters (
,) or white space.
Comparison operators are in FIQL notation:
|!=||Not Equal To|
|=ge=||Greater Than Or Equal To|
|=le=||Less Than Or Equal To|
|=c=||Contains (only for sets)|
These nine operators can be used to define all sorts of filters, for example:
name==John: find all users whose name is John
role!=CEO: find all users whose role is not CEO
age=gt=10: find all users older than 10 (exclusive)
age=ge=10: find all users older than 10 (inclusive)
role=in=('CEO','CTO','Employee'): find all users whose role is either CEO, CTO, or Employee
interests=c='sports': find all users who have sports among their set of interests
The argument can be a single value, or multiple values in parentheses that are separated by commas. A value that does not contain any reserved character or white space can be unquoted; other arguments must be enclosed in single or double quotes.
If you need to use both single and double quotes inside a quoted argument, then you must escape one of them using
\ (backslash). If you want to use
\ literally, then double it as
\\. Backslash has a special meaning only inside a quoted argument, not in unquoted argument.
Sorting expressions are also defined in RSQL syntax. They are composed of several comparison nodes, one for each sort criteria. For example:
price==ASC: sort by ascending age
To separate these nodes, both logical operators
, are permitted. Given that logical operators play no role in sorting, they are only used to separate the different comparison nodes. Sort priority is defined from left to right. This makes the nodes on the left receive higher priority than those following them.
age==ASC;price==DESC;name==ASC 1. age 2. price 3. name
Just as with filtering, each comparison node is composed of a selector, an operator, and an argument. Although, this time, the only accepted operator is
==. In the sorting nodes, the selector represents the attribute or field to sort by and the argument represents the direction in which the fields will be sorted. The keywords for ascending and descending direction are
DESC respectively. Here are some examples of sorting nodes:
age==ASC: sort by ascending age.
age==ASC;price==DESC: sort by ascending age and, in the event that there are two elements with the same age, sort those elements by descending price.