EP filters

EP filters are used for filtering EPs when quering EPR REST API to get EPs. EP filters are application-specific. Each filter have an application-wide unique ID assigned by the EPR at the moment of the filter provisioning. For each EP 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 EP filter is created, EPR performs an asynchronous recalculation of filter matches for all of the application’s EPs. Whenever an EP application version or EP metadata is updated, the filter matches/mismatches for that EP 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 EP filter events.

Filter states

Due to asynchronous nature, filters have two states: ACTIVE and PENDING.

When EP filters are created, they are in PENDING state until EP matching process is finished. If a filter is in this state, EP search by the filter is disabled.

After EP 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 EP filtering process:

  • Multiple metadata key values cannot be used in 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

MongoDB queries example

Assume the EP registered in app version app1-1 and has the metadata as described below:

{  
  "key1":1,
  "key2":"value",
  "key3":true,
  "key4":{  
    "v1":1,
    "v2":[1,2,3]
  },
  "key5":[  
    {  
      "val":5
    },
    100,
    500,
    ["val1"]
  ],
  "key6":null
}

Filter by application version only

MongoDB query:

db.endpoint.find({
    application_version: 'app1-1'
});

Filter by metadata keys and application version

MongoDB query:

db.endpoint.find({
    $and: [
        { metadata: { $elemMatch: { key: 'key4', "value.v1": { $gt: 0 } } } }, 
        { metadata: { $elemMatch: { key: 'key5', value: { $size: 4 } } } }, 
        { metadata: { $elemMatch: { key: 'key5', value: { $in: [100] } } } }, 
        { metadata: { $elemMatch: { key: 'key5', value: { $elemMatch: { $gt: 499 } } } } }, 
        { metadata: { $elemMatch: { key: 'key5', "value.0.val": { $ne: 4 } } } }, 
        { $or: [
            { metadata: { $elemMatch: { key: 'key1', value: { $gt: 0 } } } }, 
            { metadata: { $elemMatch: { key: 'key3', value: true } } }] }, 
        { metadata: { $elemMatch: { key: 'key6', value: null } } }, 
        { metadata: { $elemMatch: { key: 'key2', value: { $type: 'string' } } } }, 
        { metadata: { $elemMatch: { key: 'key2', value: { $regex: /val.*/i } } } }, 
        { application_version: 'app1-1' }]
});