Ditto utilizes a subset of RQL as language for specifying queries.
The RQL project page says about it:
Resource Query Language (RQL) is a query language designed for use in URIs with object style data structures. […]
RQL can be thought as basically a set of nestable named operators which each have a set of arguments. RQL is designed to have an extremely simple, but extensible grammar that can be written in a URL friendly query string.
An example helps more than a thousand words, so that would be the example of a simple RQL query querying
The following sections describe what the RQL syntax is capable of and which RQL operators are supported in Eclipse Ditto.
eq(foo,3), is supported by Eclipse Ditto and that Ditto added more non-specified operators, e.g.
The RQL filter specifies “what” to filter.
<property> = url-encoded-string
When not starting with a prefix
<some-prefix>:, the RQL query property specifies a field in the JSON representation
of a Thing.
For example a query property
thingId selects the Thing ID as property, a query property
an attribute with the name
location as query property.
To filter nested properties, Ditto uses the JSON Pointer notation (RFC-6901),
where the property can also start with a slash
/ or omit it, so those 2 query properties are semantically the same:
The following example shows how to apply a filter for the sub property
location of the parent property
with a forward slash as separator:
Placeholders as query properties
Currently supported placeholders for RQL expressions are:
The placeholder documentation describes which placeholder names are supported.
<value> = <number>, <string>, <placeholder>, true, false, null <number> = <double>, <integer> <string> = "url-encoded-string", 'url-encoded-string' <placeholder> = time:now, time:now_epoch_millis
String values may either be delimited using single or double quotes.
Comparison of string values
le, do not support a special “semantics” of string comparison (e.g. regarding alphabetical or lexicographical ordering).
However, you can rely on the alphabetical sorting of strings with the same length (e.g. “aaa” < “zzz”) and that the order stays the same over multiple/different filter requests.
Comparison of other data types
The following relational operators are supported.
Filter property values equal to
Example - filter things owned by “SID123”
Filter property values not equal to
Example - filter things with owner different than “SID123”
The response will contain only things which do provide an owner attribute (in this case with value 0 or not SID123).
Filter property values greater than a
Example - filter things with thing ID greater than “A000”
Filter property values greater than or equal to a
Example - filter things with thing ID “A000” or greater
Filter property values less than a
Example - filter things with thing ID lower than “A000”
Filter property values less than or equal to a
Example - filter things with thing ID “A000” or lower
Filter property values which contains at least one of the listed
Example - filter things with thing ID “A000” or “AB00” or “AZ99”
Filter property values which are like (similar) a
likeoperator is not defined in the linked RQL grammar, it is a Ditto specific operator.
Details concerning the like-operator
like operator provides some regular expression capabilities for pattern matching Strings.
The following expressions are supported:
- *endswith => match at the end of a specific String.
- startswith* => match at the beginning of a specific String.
- *contains* => match if contains a specific String.
- Th?ng => match for a wildcard character.
like(attributes/key1,"*known-chars-at-end") like(attributes/key1,"known-chars-at-start*") like(attributes/key1,"*known-chars-in-between*") like(attributes/key1,"just-som?-char?-unkn?wn")
Filter property values which exist.
existsoperator is not defined in the linked RQL grammar, it is a Ditto specific operator.
Example - filter things which have a feature with ID “feature_1”
Example - filter lamps which are located in the “living-room”
Ensure that all given queries match.
Example - filter things which are located on the “upper floor” in the “living-room”
At least one of the given queries match.
Example - filter all things located on the “upper floor”, and all things with location “living-room”
Negates the given query.
Example - filter things whose ID do not start with a common prefix
The RQL sorting part specifies in which order the result should be returned.
- Use + for an ascending sort order (URL encoded character %2B)
- Use - for a descending sort order (URL encoded character %2D)
Example - sort the list ascending by the thing ID
Example - sort the list ascending by an attribute
Example - multiple sort options
This expression will sort the list descending by location attribute.
In case there are multiple things with the same location attribute, these are sorted ascending by their ID.