NGSIv2 and NGSIv1 have different filtering mechanisms. For example, in NGSIv1,
filtering is heavily based on the use of the scope payload element. Both
approaches (NGSIv2 and NGSIv1) are described below, each in a separate section.
NGSIv2 implements Simple Query Language and Geographical Queries. They
can be used in both synchronous queries (e.g. GET /v2/entities) and
subscription notifications (in the subject.condition.expression field).
The Simple Query Language allows to define conditions that entity attributes must match, e.g. attribute "temperature" has to be greater than 40.
Examples are found in this section of the API walthrough. The full syntax definition is found in the "Simple Query Language" section of the NGSIv2 specification.
Geographical Queries allow to filter by geographical location, e.g. all the entities located closer than 15 km from the center of Madrid. Of course, properly located entities are mandatory.
Both topics (entity location and geographical queries) are dealt in detail in the "Geospacial properties of entities" and "Geographical Queries" sections of the NGSIv2 specification.
Orion Context Broker implements several filters that can be used to filter the results in NGSI10 query operations. These filters are typically used with queryContext with patterns or the convenience operation to get all entities.
As a general rule, filters used in standard operation use a scope element:
(curl localhost:1026/v1/queryContext -s -S --header 'Content-Type: application/json' \
--header 'Accept: application/json' -d @- | python -mjson.tool) <<EOF
{
"entities": [
{
"type": "myEntityType",
"isPattern": "true",
"id": ".*"
}
],
"restriction": {
"scopes": [
{
"type": "FIWARE::Filter::foobar",
"value": ""
}
]
}
}
EOF
while filters in convenience operations are included as parameters in the URL:
curl localhost:1026/v1/contextEntities?filter=value -s -S --header 'Content-Type: application/json' \
--header 'Accept: application/json' | python -mjson.tool
Filters are cumulative. In other words, you can use several scopes in the same restriction (in the case of standard operations) or several URL argument separated by '&' in order to specify several filters. The result is a logic "and" between all of them.
The scope correspoding to this type is "FIWARE::Filter::Existence".
{
"restriction": {
"scopes": [
{
"type": "FIWARE::Filter::Existence",
"value": "entity::type"
}
]
}
}
The URL parameter corresponding to this filter is 'exist'.
curl localhost:1026/v1/contextEntities?exist=entity::type ...
In the current version, the only parameter than can be checked for existence is the entity type, corresponding to "entity::type".
The scope corresponding to this type is "FIWARE::Filter::Not::Existence".
...
{
"restriction": {
"scopes": [
{
"type": "FIWARE::Filter::Not::Existence",
"value": "entity::type"
}
]
}
}
...
The URL parameter corresponding to this filter is '!exist'.
curl localhost:1026/v1/contextEntities?!exist=entity::type ...
In the current version, the only parameter than can be checked for no-existence is the entity type, corresponding to "entity::type". Note that this is the only way of selecting an "entity without type" (given that queries without type resolve to "any type", as explained in the following section).
There is no scope corresponding to this filter, given that you can use the usual entity type:
...
{
"type": "Room",
"isPattern": "...",
"id": "..."
}
...
The URL parameter corresponding to this filter is 'entity::type'.
curl localhost:1026/v1/contextEntities?entity::type=Room ...
The scope corresponding to this type is "FIWARE::Location". It is described in detail in the following section.
In the current version of Orion, there is no equivalent convenience operation filter.
The scope corresponding to this type is "FIWARE::Location::NGSIv2". It is described in detail in the following section.
Two different types of string filters are supported:
- filtering over attributes (scope type: "FIWARE::StringQuery") and
- filtering over the metadatas of attributes (scope type: "FIWARE::StringQuery::Metadata").
These scopes allow to express filtering conditions such as equality, unequality, greater/less than, in-array, range or existence (of attributes and metadata of attributes).
There isn't any URL parameter corresponding to these filters in NGSIv1.
In NGSIv2 they correspond to the q and mq URI parameters.
For a detailed syntax description of the value of the string filters or ofthe q and mq
parameters, see
NGSIv2 specification document.
You can use these scopes in NGSIv1, but take into account that in order to set attribute values to numbers, you need to use NGSIv2 (NGSIv1 always uses strings for values).
The scope corresponding to this type is "FIWARE::StringQuery".
...
{
"restriction": {
"scopes": [
{
"type": "FIWARE::StringQuery",
"value": "temperature<24;humidity==75..90;status==running"
}
]
}
}
...
In NGSIv2, the URI parameter q can be used in queries to express this scope:
curl 'localhost:1026/v2/entities?q=temperature<24;humidity==75..90;status==running'
The scope corresponding to this type is "FIWARE::StringQuery::Metadata".
...
{
"restriction": {
"scopes": [
{
"type": "FIWARE::StringQuery::Metadata",
"value": "temperature.accuracy<1;humidity.accuracy==1..2"
}
]
}
}
...
In NGSIv2, the URI parameter mq can be used in queries to express this scope:
curl 'localhost:1026/v2/entities?mq=temperature.accuracy<1;humidity.accuracy==1..2'