RQL expressions

You query Ditto using a subset of Resource Query Language (RQL) for specifying queries, filters, and conditions.

Overview

RQL is a query language designed for use in URIs with object-style data structures (see the RQL project page).

Here is a simple RQL query that filters for foo="ditto" and bar<10:

and(eq(foo,"ditto"),lt(bar,10))

This query consists of one logical operator (and) containing two relational operators, each with a property and a value.

The following sections describe what the RQL syntax is capable of and which RQL operators are supported in Eclipse Ditto.

RQL filter

The RQL filter specifies “what” to filter.

Query property

<property> = url-encoded-string

A query property specifies a field in the JSON representation of a Thing. For example, thingId selects the Thing ID, and attributes/location selects the location attribute.

Ditto uses JSON Pointer notation (RFC-6901) for nested properties. You can include or omit the leading slash – these are equivalent:

• /attributes/location
• attributes/location

Example – filter by a nested attribute:

eq(attributes/location,"kitchen")

Placeholders as query properties

When you use RQL to filter change notifications, you can use placeholders instead of Thing JSON fields:

• topic:<placeholder-name>
• resource:<placeholder-name>
• time:<placeholder-name>

See the placeholder documentation for supported names.

Query value

<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 can use single or double quotes.

String comparison

Other data types

Relational operators

eq

Filter property values equal to <value>.

eq(<property>,<value>)

Example – filter Things owned by “SID123”:

eq(attributes/owner,"SID123")

ne

Filter property values not equal to <value>.

ne(<property>,<value>)

Example – filter Things with owner different from “SID123”:

ne(attributes/owner,"SID123")

The response only contains Things that have an owner attribute (with a value other than “SID123”).

gt

Filter property values greater than <value>.

gt(<property>,<value>)

Example:

gt(thingId,"A000")

ge

Filter property values greater than or equal to <value>.

ge(<property>,<value>)

Example:

ge(thingId,"A000")

lt

Filter property values less than <value>.

lt(<property>,<value>)

Example:

lt(thingId,"A000")

le

Filter property values less than or equal to <value>.

le(<property>,<value>)

Example:

le(thingId,"A000")

in

Filter property values matching at least one of the listed values.

in(<property>,<value>,<value>, ...)

Example – filter Things with ID “A000”, “AB00”, or “AZ99”:

in(thingId,"A000","AB00","AZ99")

like

Filter property values matching a pattern (Ditto-specific operator).

like(<property>,<value>)

Supported pattern expressions:

• *endswith – match at the end of a string
• startswith* – match at the beginning of a string
• *contains* – match if a string contains the pattern
• Th?ng – match a single wildcard character

Examples:

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

ilike

Filter property values matching a pattern, case-insensitively (Ditto-specific operator).

ilike(<property>,<value>)

Supports the same patterns as like, but ignores case:

ilike(attributes/key1,"*known-CHARS-at-end")
ilike(attributes/key1,"known-chars-AT-start*")
ilike(attributes/key1,"*KNOWN-CHARS-IN-BETWEEN*")
ilike(attributes/key1,"just-som?-char?-unkn?wn")

exists

Filter for properties that exist (Ditto-specific operator).

exists(<property>)

Example – filter Things that have a Feature with ID “feature_1”:

exists(features/feature_1)

Example – filter lamps located in the “living-room”:

and(exists(features/lamp),eq(attributes/location,"living-room"))

empty

Filter property values which are absent or void of content.

empty(<property>)

A field is considered “empty” when:

• The field does not exist
• The field is null
• The field is an empty array []
• The field is an empty object {}
• The field is an empty string ""

Numeric values (including 0) and boolean values (including false) are not considered empty.

Example - filter things where tags are absent or empty

empty(attributes/tags)

Example - filter things where tags exist and have content

not(empty(attributes/tags))

Example - filter things where tags are either empty or contain “default”

or(empty(attributes/tags),eq(attributes/tags,"default"))

Logical operators

and

All given queries must match.

and(<query>,<query>, ...)

Example – filter Things on the “upper floor” in the “living-room”:

and(eq(attributes/floor,"upper floor"),eq(attributes/location,"living-room"))

or

At least one of the given queries must match.

or(<query>,<query>, ...)

Example – filter Things on the “upper floor” or in the “living-room”:

or(eq(attributes/floor,"upper floor"),eq(attributes/location,"living-room"))

not

Negate the given query.

not(<query>)

Example – filter Things whose ID does not start with a common prefix:

not(like(thingId,"org.eclipse.ditto:blocked*"))

RQL sorting

The sorting part specifies result order:

sort(<+|-><property>,<+|-><property>,...)

• Use + for ascending order (URL encoded: %2B)
• Use - for descending order (URL encoded: %2D)

Examples:

sort(+thingId)
sort(+attributes/location)
sort(-attributes/location,+thingId)

The last example sorts descending by location, then ascending by Thing ID for ties.

Sorting of string values

Sorting of other values

Further reading

• Search – search concepts and paging
• Conditional requests – using RQL as conditions for updates
• Change notifications – filtering notifications with RQL