Endpoint Filter
What is endpoint filter
Endpoint filter is a mechanism used to select specific endpoints (devices) from the entire set of registered endpoints in the Kaa platform. This filtering is based on certain conditions.
Endpoint filters can be configured to target endpoints based on various attributes such as device type, location, firmware version, custom properties, or any other metadata associated with the endpoint.
Endpoint filters are application-specific. Each filter has an application-wide unique ID assigned at the moment of the filter creation. Endpoint filters are based on MongoDB views.
Filters can be specified using powerful queries which can reference values of:
- endpoint metadata;
- endpoint application version.
Whenever an endpoint filter is created, Kaa performs an asynchronous recalculation of filter matches for all the application’s endpoints. Whenever an endpoint application version or endpoint metadata is updated, the filter matches/mismatches for that endpoint is re-evaluated.
Kaa provides REST API for managing endpoint filters and receiving lists of matching endpoints.
Filter states
Due to asynchronous nature, filters have two states: ACTIVE and PENDING.
When endpoint filters are created, they are in PENDING state until endpoint matching process is finished.
If a filter is in this state, endpoint search by the filter is disabled.
After endpoint matching is completed, filters change state to ACTIVE.
This state means a filter has been activated and is fully functional.
Filter limitations
There are several limitations related to endpoint filtering process:
- Multiple metadata key values cannot be used in the same predicate criterion because MongoDB does not support such queries.
$where operator can be used for such filtration.
For example, the following predicate is not valid:
metadata.foo > metadata.bar - On one side of a predicate, the single criterion must be a constant; on the other—metadata key or application version
- Arithmetic operations like plus, minus, divide, multiply are not natively supported by mongo query engine
- Only MongoDB query operations and functions are supported
Filter queries example
Assume the endpoint registered in application version c8u2bklah5mkbalggie0-v1 and has the following metadata:
{
"name": "Smart meter 1",
"serial": "CNF-77C-Sk-B1200e-Xt7",
"city": "Kyiv",
"model": "Qubino Smart Meter 3-Phase",
"type": "electric",
"lat": 50.4504,
"lon": 30.5245
}
Filter by application version only
{
"application_version": "c8u2bklah5mkbalggie0-v1"
}
Filter by city metadata key having value Kyiv
{
"metadata": {
"$elemMatch": {
"key": "city",
"value": "Kyiv"
}
}
}
Filter by city metadata key having value Kyiv and application version c8u2bklah5mkbalggie0-v1
{
"$and": [
{
"application_version": "c8u2bklah5mkbalggie0-v1"
},
{
"metadata": {
"$elemMatch": {
"key": "city",
"value": "Kyiv"
}
}
}
]
}
To create endpoint filter, go to Device management -> Endpoint filters, and click “Add filter” button.
and create the filter specifying the filter query.
What you can do with endpoint filter using Kaa
View the matching endpoints
From the page of the created filter you can vew all the matching endpoints in the Matching endpoints widget table.
List matching endpoints via REST API
You can query list of matching endpoints with the help of endpoint filter REST API.
Example of querying matching endpoints by the filter with ID 3febb1a7-f0a5-4f9c-a24d-40010111b62d from Kaa Cloud in the c8u2bklah5mkbalggie0 application.
Initialize $ACCESS_TOKEN with the access token, and $APPLICATION with your application name.
curl -H "Authorization: Bearer $ACCESS_TOKEN" https://cloud.kaaiot.com/epr/api/v1/endpoints?applicationName=$APPLICATION&filterId=3febb1a7-f0a5-4f9c-a24d-40010111b62d
Send command to matching endpoints
Imagine you want to start over-the-air update only for those endpoints that match the filter (which are in Kyiv in our case). For that, use Command execution widget.
Send configuration to matching endpoints
Refer to REST API.