RSQL

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).

Filtering

RSQL expression is composed of one or more comparisons, related to each other using logical operators:

OperatorDescription
;Logical AND
,Logical OR

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 CEO or whose name is John.

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 (", ', (, ), >, <, =, !, ~, ; and ,) or white space.

Comparison operators are in FIQL notation:

Basic OperatorDescription
==Equal To
!=Not Equal To
=gt=Greater Than
=ge=Greater Than Or Equal To
=lt=Less Than
=le=Less Than Or Equal To
=in=In
=out=Not In
=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

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

Syntax

To separate these nodes, both logical operators ; and , 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.

Sort priority: 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 ASC and 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.