Edit this page

The search aspect of Ditto can be accessed via an HTTP API.

The concepts of the RQL expression, RQL sorting and RQL paging are mapped to HTTP as query parameters which are added to GET requests to the search endpoint:


If the filter parameter is omitted, the result contains all Things the authenticated user is allowed to read.

Optionally a namespaces parameter can be added to search only in the given namespaces.

Query parameters

In order to define for which Things to search, the filter query parameter has to be added.
In order to change the sorting and limit the result (also to do paging), the option parameter has to be added. Default values of each option is documented here.

Complex example:

GET .../search/things?filter=eq(attributes/location,"living-room")&option=sort(+thingId),limit(0,5)&namespaces=org

Another Complex example with the namespaces parameter:

GET .../search/things?filter=eq(attributes/location,"living-room")&namespaces=org.eclipse.ditto,foo.bar

The HTTP search API can also profit from the partial request concept of the API:
Additionally to a filter and options, a fields parameter may be specified in order to select which data of the result set to retrieve.

Example which only returns thingId and the manufacturer attribute of the found Things:

GET .../search/things?filter=eq(attributes/location,"living-room")&fields=thingId,attributes/manufacturer

With the namespaces parameter, the result can be limited to the given namespaces.

Example which only returns Things with the given namespaces prefix:

GET .../search/things?namespaces=org.eclipse.ditto,foo.bar

Search count

Search counts can be made against this endpoint:


Complex example:

GET .../search/things/count?filter=eq(attributes/location,"living-room")
Tags: http search rql