Endpoint filters

Endpoint filters are used for filtering endpoints when querying EPR REST API to get endpoints. Endpoint filters are application-specific. Each filter has an application-wide unique ID assigned by the EPR at the moment of the filter provisioning. For each endpoint filter the corresponding MongoDB view filter-{filterId} is created.

Filters can be specified using powerful queries which can reference values of:

  • endpoint metadata;
  • endpoint application version name.

Whenever an endpoint filter is created, EPR performs an asynchronous recalculation of filter matches for all of the application’s endpoints. Whenever an endpoint application version or endpoint metadata is updated, the filter matches/mismatches for that endpoint is re-evaluated.

EPR provides REST API for managing endpoint filters and receiving lists of matching endpoints.

For each named filter, EPR broadcasts endpoint filter events to a distinct topic. Endpoint filter events indicate when endpoints match or mismatch a filter (usually, due to metadata or application version name update). See Endpoint filter events.

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 app version app1-v1 and has the metadata as described below:

{  
  "OSVersion": "2",
  "serial": "CNF-77C-Sk-B1200e-Xt7",
  "status": "active",
  "location": {
    "latitude": 27.764827,
    "longitude": -35.213
  }
}

Filter by application version only

{
    "application_version": "app1-v1"
}

Filter by metadata key

{
    "metadata": {
        "$elemMatch": {
            "key": "OSVersion",
            "value": "2"
        }
    }
}

Filter by metadata key and application version

{
    "$and": [
        {
            "application_version": "app1-v1"
        },
        {
            "metadata": {
                "$elemMatch": {
                    "key": "serial",
                    "value": "CNF-77C-Sk-B1200e-Xt7"
                }
            }
        }
    ]
}