How can I quickly test how Reltio comparator classes evaluate two values and look at the returned equals flag and relevance score?

Quickly test how Reltio comparator classes evaluate two values (simple strings or structured objects) and see the returned equals flag and relevance score. Helpful in tuning match rules and validating comparator behavior before changing production configuration.

Example:

POST https://<environment>.reltio.com/reltio/tools/matching/compare" 
Request body:
{
"first": "third ave",
"second": "3rd ave",
"comparatorClass": {"class": "com.reltio.match.comparator.DynamicDamerauLevenshteinDistance"},
"fuzzy": true
}'

Overview

The /tools/matching/compare endpoint compares a first value with a second value using a specified comparator class. It supports:

• Simple, single-attribute comparisons (e.g., strings like names, streets, phone numbers)
• Complex, multi-attribute comparisons (e.g., addresses broken into line/city/state/postalCode)
• Optional fuzzy logic when supported by the comparator

The response returns:

• equals — whether the comparator says the values match (boolean)
• relevance — similarity score in the range 0.0–1.0
• details — per-attribute breakdown for multi-attribute comparators

Tip: This endpoint is a diagnostic tool. It does not create matches or update entities. Use it to verify comparator behavior and thresholds before applying changes to your match rules.

Endpoint

POST https://<environment>.reltio.com/reltio/tools/matching/compare

Headers

• Content-Type: application/json
• Standard Reltio authentication headers (as used in your environment)

Request Body Schema

{
"first": <any>,
"second": <any>,
"comparatorClass": {
"class": "<fully.qualified.ComparatorClass>",
"parameters": [
{
"parameter": "<name>",
"values": [ <value | object>, ... ]
}
]
},
"fuzzy": <boolean>
}

Fields

• first (required) — The first input to compare. Can be a string or a JSON object (e.g., a structured address).
• second (required) — The second input to compare.
• comparatorClass (required) — Which comparator to use, plus any parameters.
  • class — Fully qualified Java class name of the comparator (e.g., com.reltio.match.comparator.DynamicDamerauLevenshteinDistance).
  • parameters — Optional list of comparator-specific settings. Each item has a parameter name and a values array (values may be primitives or objects depending on the comparator).
• fuzzy (optional) — Enables fuzzy comparison where supported. When true, the comparator may tolerate typographical differences, abbreviations, or transpositions and return a graded relevance score.

Responses

{
"equals": <boolean>,
"relevance": <number 0.0-1.0>,
"details": {
"<attribute>": { "equals": <boolean>, "relevance": <number> },
"...": {}
}
}

• equals — Final comparator decision. For fuzzy comparators, this usually depends on an internal or configured threshold.
• relevance — Overall similarity score. The closer to 1.0, the more similar the values are.
• details — Present for multi-attribute comparisons, showing per-attribute results.

Best practice: Use relevance to understand how close two values are. If needed, implement your own acceptance threshold for your use case.

Examples

1) Simple string comparison (fuzzy)

Request

{
"first": "third ave",
"second": "3rd ave",
"comparatorClass": {
"class": "com.reltio.match.comparator.DynamicDamerauLevenshteinDistance"
},
"fuzzy": true
}

Typical response

{
"fuzzy": true,
"first": "third ave",
"second": "3rd ave",
"equals": false,
"relevance": 0.8888888888888888
}

Explanation: The strings are highly similar (relevance ≈ 0.89), but the comparator’s equality threshold is not met, so equals is false.

2) Custom pattern-based comparison (grouped comparators)

Request

{
"first": "123 Lawson Ln",
"second": "2225 Lawson Ln",
"comparatorClass": {
"parameters": [
{
"parameter": "groups",
"values": [
{ "className": "com.reltio.match.comparator.AddressLineComparator" },
{ "pattern": "\\d+", "className": "com.reltio.match.comparator.BasicStringComparator" }
]
}
],
"class": "com.reltio.match.comparator.CustomComparator"
},
"fuzzy": false
}

Explanation: A CustomComparator delegates to different comparators by pattern (e.g., numeric tokens vs. non-numeric address text) to control how house numbers and street names influence the result.

3) Multi-attribute address comparison

Request

{
"first": {
"addressLine1": "123 Main St.",
"city": "San Francisco",
"state": "CA",
"postalCode": "94105"
},
"second": {
"addressLine1": "123 Main Street",
"city": "San Francisco",
"state": "California",
"postalCode": "94105-1234"
},
"comparatorClass": {
"class": "com.reltio.match.comparator.MultiAttributeComparator",
"parameters": [
{
"parameter": "comparators",
"values": [
{
"attribute": "addressLine1",
"className": "com.reltio.match.comparator.AddressLineComparator",
"parameters": [ { "parameter": "ignoreCase", "values": [true] } ]
},
{ "attribute": "city", "className": "com.reltio.match.comparator.BasicStringComparator" },
{
"attribute": "state",
"className": "com.reltio.match.comparator.StateComparator",
"parameters": [ { "parameter": "normalize", "values": [true] } ]
},
{
"attribute": "postalCode",
"className": "com.reltio.match.comparator.PostalCodeComparator",
"parameters": [ { "parameter": "ignoreExtension", "values": [true] } ]
}
]
}
]
},
"fuzzy": true
}

Typical response

{
"equals": true,
"relevance": 0.95,
"details": {
"addressLine1": { "equals": true, "relevance": 1.0 },
"city": { "equals": true, "relevance": 1.0 },
"state": { "equals": false, "relevance": 0.8 },
"postalCode": { "equals": true, "relevance": 1.0 }
}
}

Explanation: Each attribute is compared by a dedicated comparator. The overall comparison is a strong match despite the state long/short-form difference and the ZIP+4 extension.

Interpreting results

• High relevance, equals=false — Inputs are similar but failed the comparator’s equality threshold. Consider adjusting thresholds or using the score in your own logic.
• Low relevance, equals=true — Possible if the comparator treats certain tokens as decisive (e.g., an ID match). Review comparator parameters.
• Use details — For multi-attribute cases, identify which field(s) drive disagreement.

Best practices

1. Mirror production comparators — Use the same classes and parameters you plan to deploy in match rules for realistic results.
2. Normalize inputs — Apply the same cleansing/standardization you use during ingestion (case, punctuation, trimming) unless the comparator handles it.
3. Document thresholds — Record what relevance ranges you consider equivalent for your domain to make tuning repeatable.
4. Start simple — Validate single-attribute behavior before assembling multi-attribute comparators.

FAQ

Q: What  fuzzy really change?
A: When supported by the comparator, fuzzy: true allows approximate matching (e.g., edit distance, token transpositions). It typically increases the chance of a partial similarity score rather than a strict mismatch.

Q: Is relevance always the same as equals?
A: No. equals is the comparator’s pass/fail decision. relevance is a continuous similarity score that helps you tune thresholds.

Q: Can I compare arrays or nested structures?
A: Yes, as long as your chosen comparator supports structured inputs (e.g., MultiAttributeComparator). Map each attribute to an appropriate comparator via parameters.