How to create advanced subscriptions expression at Orion Context Broker NGSIv2?

Question

According to official documentation of Orion Context Broker NGSIv2 :

You can include filtering expressions in conditions. For example, to get notified not only if pressure changes, but if it changes within the range 700-800. This is an advanced topic, see the "Subscriptions" section in the NGSIv2 specification.

At NGSIv2 subscriptions there is no notifyConditions such as NGSIv1 , it was replaced by subject.condition object:

condition: Condition to trigger notifications. This field is optional and it may contain two properties, both optional:

attrs: array of attribute names

expression: an expression composed of q, mq, georel, geometry and coords (see "List entities" operation above about this field)

When we use subject.condition.attrs, it contains an array of attributes names, these names define the "triggering attributes", i.e. attributes that upon creation/change due to entity creation or update trigger the notification.

But, for subject.condition.expression there is not example at official documentations.

Getting pieces of puzzle is possible to deduce :

Is possible do combine subject.condition.expression and subject.condition.attrs. If I set and attribute different of expression,eg. attr foo with expression 'boo>10' what it will do ? Will this behave like an OR or AND ?
Is possible to set multiple expressions. Will this behave like an OR or AND ?

It would be nice to have some examples of these more complex subscriptions combining the different ways of delimiting the entities in the subscription.

NOTE: This question is related to Orion Version 1.7.0+

fgalan fgalan · Accepted Answer · 2017-08-04T18:03:23

I think the following example, from the NGSIv2 Overview for Developers That Already Know NGSIv1 presentation (slide 34 in the current version), could help to clarify.

Example: subscribe to speed changes in any entities of any type ending with Vehicle (such as RoadVehicle, AirVehicle, etc.) whenever speed is greater than 90 its average metadata is between 80 and 90 and the vehicle distance to Madrid city center is less than 100 km

Request:

POST /v2/subscriptions
...
{  
  "subject": {
    "entities": [
     {
        "idPattern": ".*",
        "typePattern": ".*Vehicle"
     },
    ],
    "condition": {
      "attrs": [ "speed"  ],
      "expression":  {
         "q": "speed>90",
         "mq": "speed.average==80..100",
         "georel": "near;maxDistance:100000",
         "geometry": "point",
         "coords": "40.418889,-3.691944"
      }
      }
    },
   ...
}

As this example illustrates, you can use different conditions (q, mq, geoquery, etc.) and they are interpreted in the AND sense. Morevoer, q and mq allow complex expressions interpreted also in the AND sense, such as:

"q": "speed>90;engine!=fail",

Note that q and mq when they appear in subscriptions expression follow the same rules than the ones when they appear in synchronous queries (i.e. GET /v2/entities?q=...). These rules are described in "Simple Query Language" section in the NGSIv2 specification.

How to create advanced subscriptions expression at Orion Context Broker NGSIv2?

1 Answers