The Match Groups Construct

Learn about the matchGroups construct, which defines match groups, rules, and operands for comparing, grouping, or merging profiles during matching.

If you wish to enable matching for a specific entity type in your tenant, then you will include the matchGroups section within the definition of the entity type in the metadata configuration of your tenant. (Again, this section is optional and only needs to exist if you wish to perform matching for a specific entity type in your tenant.) The matchGroups section will contain one or more match groups, each containing a single rule and other elements that support the rule; Each match group should generally represent a tactic for finding and evaluating match pairs, different from the other match groups.

Anatomy of a Classic Match Group

Looking at a match group in a JSON editor, you can easily see the high-level, classic elements within it. The primary element is the rule which defines a boolean formula (see the and operator that anchors the boolean formula in this example) for evaluating the similarity of a pair of profiles given to the match group for evaluation. It is also within the rule element that four other very common elements are held: ignoreInToken (optional), Cleanse (optional), matchTokenClasses (required), and comparatorClasses (required). The remaining elements that are visible (URI, label, and so on), and some not shown in the snapshot, surround the rule and provide additional declarations that affect the behavior of the group and in essence, the rule. The following image shows the classic structure of a match group:

Thus, the overall structure for a match group within the matchGroups section looks like this:

{
  "matchGroups": [
    {
      "uri": "configuration/entityTypes/<EntityType>/matchGroups/<GroupName>",   // required, unique ID
      "label": "<short UI name>",                                                // required
      "type": "automatic | suspect | relevance_based | automatic_grouping | <custom>", // required
      "scope": "ALL | INTERNAL | EXTERNAL | NONE",                               // optional
      "useOvOnly": "true | false",                                               // optional

      // Exactly one of the following is present:
      "rule": {
        "ignoreInToken": [ "<attribute-URI>", "..." ],                           // optional
        "cleanse": [ { "cleanseAdapter": "<class>", "mappings": [ ... ] } ],     // optional

        "matchTokenClasses": {
          "mapping": [
            { "attribute": "<attribute-URI>", "class": "<token-class>" }
          ]
        },
        "comparatorClasses": {
          "mapping": [
            { "attribute": "<attribute-URI>", "class": "<comparator-class>" }
          ]
        },

        // Comparison formula (nestable with AND/OR; NOT allowed only in positive rules)
        "and": {
          // Attribute comparison operators
          "exact": [ "<attribute-URI>", "..." ],
          "fuzzy": [ "<attribute-URI>", "..." ],
          "exactOrNull": [ "<attribute-URI>", "..." ],
          "exactOrAllNull": [ "<attribute-URI>", "..." ],
          "notExact": [
            {
              "uri": "<attribute-URI>"
            }
          ],
          "multi": [
            {
              "uri": "<multi-attribute-URI>",
              "attributes": [
                "<attribute-URI-1>",
                "<attribute-URI-2>",
                "..."
              ]
            }
          ],

          // Helper operators
          "equals": [ { "uri": "<attribute-URI>", "values": ["A","B"] } ],
          "notEquals": [ { "uri": "<attribute-URI>", "values": ["X"] } ],
          "in": [ { "uri": "<attribute-URI>", "values": ["Y","Z"] } ],
          "nullValues": [ "<attribute-URI>", "..." ]
        },

        // Relevance-based extensions (only when type = relevance_based)
        // "weights": [ { "attribute": "<attribute-URI>", "weight": 0.40 }, ... ],
        // "actionThresholds": [
        //   { "type": "auto_merge",      "threshold": "0.80-1.00" },
        //   { "type": "potential_match", "threshold": "0.40-0.80" }
        // ]
      },

      // OR
      // "negativeRule": { ...same structure, but no support for 'not' ... },

      "scoreStandalone": 0,   // optional
      "scoreIncremental": 0   // optional
    }
  ]
}

Important: A match group can contain either a rule or a negativeRule, but never both.

Just to gain some quick familiarity, here is an example of an actual match group JSON within a matchGroups section. Notice that it begins with a unique uri, and the actual rule component in this example is five lines down from the top.

Classic Match Rule - Sample

The actual JSON that is represented at a high-level above is detailed below.

"uri": "configuration/entityTypes/HCP/matchGroups/MatchonFirstNameandLastName",
  "label": "Match on FirstName and LastName",
  "type": "suspect",
  "scope": "ALL",
  "useOvOnly": "true",
  "rule": {
    "ignoreInToken": [
      "configuration/entityTypes/HCP/attributes/FirstName"
    ],
    "cleanse": [
      {
        "cleanseAdapter": "com.reltio.cleanse.impl.NameDictionaryCleanser",
        "mappings": [
          {
            "attribute": "configuration/entityTypes/HCP/attributes/FirstName",
            "cleanseAttribute": "configuration/entityTypes/HCP/attributes/FirstName"
          }
        ]
      }
    ],
    "matchTokenClasses": {
      "mapping": [
        {
          "attribute": "configuration/entityTypes/HCP/attributes/FirstName",
          "class": "com.reltio.match.token.DoubleMetaphoneMatchToken"
        }
      ]
    },
    "comparatorClasses": {
      "mapping": [
        {
          "attribute": "configuration/entityTypes/HCP/attributes/FirstName",
          "class": "com.reltio.match.comparator.DoubleMetaphoneComparator"
        }
      ]
    },
    "and": {
      "exact": [
        "configuration/entityTypes/HCP/attributes/LastName"
      ],
      "equals": [
        {
          "value": "Physician",
          "values": [
            "Physician"
          ],
          "uri": "configuration/entityTypes/HCP/attributes/HCPType"
        }
      ],
      "fuzzy": [
        "configuration/entityTypes/HCP/attributes/FirstName"
      ]
    }
  },
  "scoreStandalone": 0,
  "scoreIncremental": 0}

Most Commonly Used Elements of a Match Group

The following 11 elements are the most commonly used in a match group. Each is explained in detail in the sections that follow. Many should look familiar based on the JSON snapshot shown previously.

Table 1. Match Group Elements
Element	Required/Optional	Purpose in the Match Group
`uri`	Required	Unique namespace of the rule
`label`	Required	Your description of the rule, displayed in the MDM UI
`type`	Required	Governs the directive of the rule if the rule resolves to TRUE. You can define the following types, each with its directive shown on the right: automatic - merge the pair of profiles suspect - present the profiles to a data steward for review relevance_based - use user-designed scoring to determine the outcome automatic_grouping - group matching profiles together without merging them into a single consolidated profile <custom> - allow user to define her own rule type
`scope`	Optional	Governs whether match rules are enabled, disabled, apply to tenant records only and/or external matching.
`useOvOnly`	Optional	Restricts matching to only the OV within the attribute
`rule, negativeRule`	Required	One of them is required
`ignoreInToken`	Optional	Enables selective token suppression if needed
`cleanse`	Optional	Can provide on-the-fly cleansing of data
`matchTokenClasses`	Required	Declares which Token Classes should be utilized
`comparatorClasses`	Required	Declares which comparator Classes should be utilized
`comparison formula`	Required	Defines the attributes and operators used for determining similarity. Supported operands include: exact fuzzy exactOrNull exactOrAllNull notExact multi equals notEquals in nullValues

Unify and manage your data

The Match Groups Construct

Anatomy of a Classic Match Group

Classic Match Rule - Sample

Most Commonly Used Elements of a Match Group

Footer