Resource Query Language
Last updated
Was this helpful?
Last updated
Was this helpful?
Resource Query Language (RQL) is a query language used by the Marketplace Platform in its REST API. It is used for querying and manipulating resources in the Marketplace Platform's .
With RQL, you can filter, sort, paginate, and project data. It is simple to use but flexible enough to handle complex scenarios.
RQL consists of a set of operators that can be classified into three main categories:
Comparison operators - These perform comparisons like equals, greater than, etc.
Logical operators - These combine multiple conditions.
Algorithmic operators - These handle functionalities like sorting and pagination.
Operators are formatted as operator(arg1,arg2,...)
. Complex expressions can be created by nesting these operators.
Suppose you want to list all users with a specific domain. Implementing filtering is essential, and this is where RQL comes in.
To display all users with the first name 'Buzz, your GET
request will look like this:
The same expression can be written as:
To sort users based on their first name, your GET
request will look like this:
To sort in the opposite direction, the '-' operator can be used:
To paginate your results with a limit of 10 users and to retrieve the third page (offset 20):
The first parameter limit=10
expresses the number of users to return
The second parameter offset=20
offsets the starting position in the result set. The first 20 users will be skipped.
To request specific fields, such as forstName
, lastName
, and email
to be included, the select=+
operator can be used:
To request certain fields to be excluded, the select=-
operator can be used:
To search for all users with the first name starting from 'Bu', the following query can be used:
the operator ilike
performs a case-insensitive search.
Logical operators can be used to combine multiple operators. For example, to filter users with first name 'Buzz' and last name 'Astral:
In simple cases, a combined expression can also be written in the following form:
or (<condition1>, <condition2>, ...)
Returns records that satisfy at least one of the specified conditions.
and (<condition1>, <condition2>, ...)
Returns records that satisfy all of the specified conditions.
not (<condition>)
Returns records that do not satisfy the specified condition.
empty ( )
Constant that is used to represent an empty string. Example: /users?firstName=empty()
null ( )
Constant that is used to represent an unassigned ("null") value. Example: /users?firstName=null()
order = +<property1>,-<property2>, ...
Sorts the returned records by <property>
. +
represents the ascending order, while -
represents the descending order.
select = +<property1>, -<property2>, ...
Used to add and remove certain objects from the representation.
offset = <value>
Offsets the starting position in the resulting set.
limit = <value>
Limits the number of returned records by the specified value.
eq (<property>, <value>)
Filters records where <property>
exactly matches the <value>
.
ne (<property>, <value>)
Filters records where <property>
does not match the <value>
.
gt (<property>, <value>)
Filters records where <property>
is greater than the <value>
.
ge (<property>, <value>)
Filters records where <property>
is greater or equal to the <value>
.
lt (<property>, <value>)
Filters records where <property>
is less than the <value>
.
le (<property>, <value>)
Filters records where <property>
is less than or equal to the <value>
.
ilike (<property>, <value>)
Filters records where <property>
contains <value>
as a substring, the comparison is case-insensitive.
in (<property>,(<value1>,<value2>,...))
Filters records where <property>
matches any of the listed <value>s
.
out (<property>,(<value1>,<value2>,...))
Filters records where <property>
matches none of the listed <value>s
.
any (<collection>, <condition>)
Filters records by applying <condition>
to the nested <collection>
.
all (<collection>, <condition>)
Filters records by applying <condition>
to the nested <collection>
.
To pass special characters (like, &^$?) or whitespaces as values to RQL operators, enclose them in either double quotes (") or single quotes (') as shown in the following example:
If you need to include a quotation mark within the value, you can do so by enclosing it with a different type of quotation mark, as shown in the following example:
Allowing you to pass these special symbols as values.
The asterisk (*) character has a special meaning in the ilike
operator, matching zero or more characters in its place from the parameter value. For example, the "*dog" pattern will match strings like "big dog" and "dog," but it will not match "big dog!" because of the exclamation mark.
If you need to use the asterisk (*) character itself in the pattern, you can escape it as '*', as shown in the following example:
The ilike operator in this case will be searching for the literal value “The*” at the beginning of the firstName property.