Overview

RQL is a functional style query syntax for use in REST API's. RQL is introduced into an API call, conventionally with a where= query parameter in the API URL.

Given an REST API that returns one or more resources as an array of JSON objects, RQL filters that list of resources based on the values of the fields in each JSON object in the resource array.

An RQL expression evaluates to boolean true or false. true indicates that the associated resource should be selected.

An example RQL call appended to a typical REST API URL would be:

http://api.myhost.com/users?where=and(eq(name,'John'),gt(age,18))

This would query the users resource collection for all resources where the name field is John and the age field has a numeric value > 18.

RQL is is designed to be able to map to a variety of backend data sources by means of a native binding to safely expose a subset of the native query language of the underlying database. It is designed for use with relational data. Data is organized as collections of resources. A resource is equivalent to a database document in no-SQL or table row in SQL databases. Each resource contains one or more fields, referred to as columns in SQL databases. Fields can contain references to other resources.

Encoding

RQL uses non-URI safe characters and so must be encoded to be URI safe before transmission. Spaces are allowed in the RQL expression, but not inside identifiers (operator or field names).

Identifiers

Fields are referenced by their name, or identifier. Field identifiers must start with an alpha character and then one or more alphanumeric characters. An identifier can either be for a field or for another resource collection. Each resource is assumed to have a unique id, conventionally in a field with the name id.

Types

The syntax supports and range of data types. These data types are a superset of those available in JSON & BSON, are mapped to equivalent data types in the underlying database where available. Types that are not supported directly by JSON are encoded as JSON strings.

RQL Type	JSON Type	.NET Type	BSON Type	RQL Example(s)
Null	Null	Null	Null	null
Boolean	Boolean	Boolean	Boolean	true false
Integer	Number	Int32	Number	123 -57
Double	Number	Double	Number	3.1415 -0.17
String	String	String	String	'The quick brown fox'
Id	String	RqlId	ObjectId	$01abc57173deaf310e270
UTC DateTime	String	RqlDateTime	ISODate	@2013-11-01T17:15:30Z
Tuple	Array	Array List<T>	Array	(10,15,20,25)

All values in a tuple must be of the same type.

The RQL compiler for the native database will typically try to convert parameters to the correct underlying data type for the database field.

Sorting & Field Selection

As well as the query language itself, RQL provides parsers for sorting with the SortSpecParser class, and field selection with the FieldSpecParser class. See the specific database driver bindings for more details. By convention you add sorting with a sortBy= parameter and field selection with a fields= parameter.