Resource Query Language

Resource Query Language (RQL) is a query language used by the Marketplace Platform in its REST API.

Introduction

The Resource Query Language (or RQL) is used for querying and manipulating resources in the Marketplace Platform's REST API. With RQL, you can filter, sort, paginate, and project data. It is simple to use but flexible enough to handle complex scenarios.

Using RQL

RQL consists of a set of operators that can be classified into three main categories:

1. Comparison Operators: These perform comparisons like equals, greater than, etc.

2. Logical Operators: These combine multiple conditions.

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

Practical Examples

Suppose you want to list all users with a specific domain. Implementing filtering is essential, and this is where RQL comes in.

Basic Filtering

To display all users with the first name "Buzz", your GET request would look like this:

GET /v1/accounts/users?firstName=Buzz

the same expression can be written as:

GET /v1/accounts/users?eq(firstName,Buzz)

Sorting

To sort users based on their first name, your GET request would look like this:

GET /v1/accounts/users?order=firstName

To sort in the opposite direction, the '-' operator can be used:

GET /v1/accounts/users?order=-firstName

Pagination

To paginate your results with a limit of 10 users and to retrieve the third page (offset 20):

GET /v1/accounts/users?limit=10&offset=20

• The first parameter limit=10 expresses the number of users to return

• Second parameter offset=20 offsets the starting position in the result set. The first 20 users will be skipped.

Projection

To request specific fields, such as forstName, lastName, and email to be included, the select=+ operator can be used:

GET /v1/accounts/users?select=+firstName,+lastName,+email

To request certain fields to be excluded, the select=- operator can be used:

GET /v1/accounts/users?select=-firstName,-lastName,-email

Search

To search for all users with the firstName starting from 'Bu', the following query can be used:

GET /v1/accounts/users?ilike(firstName,Bu*)

the operator ilike performs a case-insensitive search.

Combining Operators

Logical operators can be used to combine multiple operators. For example, to filter users with first name "Buzz" and last name "Astral":

GET /v1/accounts/users?and(eq(firstName,Buzz),eq(lastName,Astral))

In simple cases, a combined expression can also be written in the following form:

GET /v1/accounts/users?firstName=Buzz&lastName=Astral

Operators

Function	Description
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> .

Advanced use cases

Special Characters in Values

To pass special characters (e.g., &^$?) or whitespaces as values to RQL operators, enclose them in either double quotes (") or single quotes (') as shown in the following example:

GET /v1/accounts/users?firstName="Buzz !!!"

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:

GET /v1/accounts/users?firstName="Buzz with the ' Quote"

Allowing you to pass these special symbols as values.

The Asterisk Character and the ilike operator

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:

GET /v1/accounts/users?ilike(firstName,"The\**")

The ilike operator in this case will be searching for the literal value “The*” at the beginning of the firstName property.