Table of contents

About events

By default, the digital twin layer will notify all consumers with read permission on a specific thing about all changes applied to the thing entity. This type of signal is also known as ‘change event’.

However, if your application prefers to only be notified upon a specific kind of events, you can apply filtering and thus help to reduce traffic load.

You can influence how much or less events you will consume on the topics you subscribed for, via connections of any type:

WebSocket
applicable for pure WebSocket connection, but also for the case you use a Java client
Server Sent Events (SSE)
applicable for Web applications using e.g. Java script for automatically retrieving updates via an HTTP connection
AMQP
Apache Kafka
MQTT

Well-tried syntax:

The logic on how to express your filtering criteria for events is very similar with the syntax for filtering at our search endpoint.

Examples:

This application is only interested in change events, which report a counter attribute greater than 10.

 filter=gt(attributes/counter,10)

This application is only interested in events from things in namespace my.namespace AND which report a counter property of a feature with ID “myfeature”, with a value greater than 10.

 namespaces=my.namespace&filter=gt(features/myfeature/properties/counter,10)

Restrictions

Please be aware that the at least some part of the filter might need to be URL-encoded in order to avoid ambiguous interpretations. E.g. in case your thing ID contains special characters, such as brackets (), colons :, comma , , and &, etc., these could be wrongly interpreted as a delimiter.

In doubt, we strongly recommend encoding the complete filter.

Quote form Eclipse Ditto
All filters are specified in an URL query format, therefore their values should be URL encoded before sending them to the backend. The equal = and the ampersand & character must be encoded in any RQL filter!

Namespace selection

Example - events concerning things within one of the specific namespaces

namespaces=com.bosch.si,my.namespace

Deviating from the namespace filtering concept for search, as soon as we are talking about events and you omit this type of selection, you will retrieve events of things of any namespace, as long as you have permission to read the resource.
The permissions is commonly defined by the thing owner in form of the policy associated to the thing entity.

RQL filter

See details at Search > Parameters and operations for all Relational operators and Logical operators.

When using a negating expression, such as not or ne, (not equal) please keep in mind that you might experience a longer time to get the response. Compared to other search operators we observed longer response times ourselves.

Example

Find a vivid example on how to mock applications and experience the filtering in Eclipse Ditto’s blog post section > Selective push notifications available.