Match Criteria on a Single Property ($msp)



A search that specifies several criteria on properties may sometimes yield unexpected results.

This is because items are frequently annotated with several properties, and as long as any criterion is true for any property, the item will be returned in a regular find.

But sometimes, we need to find items in which a single specific property answers several criteria. For this purpose we use the $msp (match on single property) operator.

The fundamental difference between a regular find and using the $msp operator is:

  • find will return an item if ANY of its properties answer ALL of the criteria in the search term.

  • $msp will only return an item if at least ONE of its properties answers ALL of the criteria in the $msp term.

Here is an example.

Consider two items A and B.

A has a license property with value AGPL-V3

B has two license properties . One is LGPL-2.1, and the other LGPL-2.2


Now let's assume we want to find items that use any variety of GPL license as long as it's NOT LGPL-2.1.

In our example we would expect to get both Items A and B returned since A has AGPL-V3 and B has LGPL-2.2.

As a first thought, we might write our query as follows:

            "@license":{"$match": "*GPL*"},
                "@license":{"$nmatch": "LGPL-2.1*"}

But this query only returns item A.

Item A is returned because it clearly answers both criteria: "@license":{"$match": "*GPL*"} and "@license":{"$nmatch": "LGPL-2.1*"}

Item B is not returned because it has the property license=LGPL-2.1 which does not meet the criterion of "@license":{"$nmatch": "LGPL-2.1*"}.

If we use the $msp operator as follows:

                        "$msp": [
                        "@license":{"$match": "*GPL*"},
                        "@license":{"$nmatch": "LGPL-2.1*"}

Then both Item A and Item B are returned.

Item A is returned because it has the @license property AGPL-V3 which meets both the {"@license":{"$match": "*GPL*"}} criterion and the "@license":{"$nmatch": "LGPL-2.1*"} criterion.

Item B is returned because it has the @license property LGPL-2.2 which also meets both the{"@license":{"$match": "*GPL*"}} criterion and the "@license":{"$nmatch": "LGPL-2.1*"} criterion.


Note that the $msp operator works equally well on all domains that have properties: item, module and build.