Problem Description
You may notice that some match rules are not producing results, even when attribute values should align. In the Verify Matches API, rules may appear as “bypassed” with matched=false. This typically indicates over-collision tokens, which occur when match rules generate excessive numbers of tokens.
Why This Happens
Over-collision tokens occur when the system generates too many match tokens for the same attributes across different rules.
Entities with over-collision tokens are excluded from participating in match processing.
This can often be triggered after a large data load or configuration change that introduces new data patterns.
Symptoms
Verify Matches shows the rule present but bypassed.
Matches or Scorecard Matches API does not return results for the rule.
Warning messages in logs or responses about token over-collisions.
Troubleshooting Steps
1. Check for Over-Collision Tokens
Run the Search Over-Collisioned Tokens API:
POST {{URL}}/reltio/api/{{tenantID}}/entities/_matches/_searchOvercollisionedThis will show entities affected by over-collision tokens.
2. Tune Match Rules
Review match rule configurations.
Simplify rules or adjust fuzzy/exact criteria to reduce the number of tokens generated.
Ensure rules are optimized and do not overlap excessively.
3. Remove Over-Collision Tokens
Use the Remove Over-Collision Tokens API to clean them up. This removes invalid tokens and prepares the system for a rebuild.
POST https://{{env}}.reltio.com/reltio/api/{{tenantID}}/removeOvercollisionedTokens?remove=true&distributed=true&taskPartsCount=4
4. Rebuild the Match Table
Run the Rebuild Match Table Task (reference Rebuild Match Table Task Documentation)
Rebuilding ensures that matches are recalculated using the tuned rules.
5. Verify Matches Again
After the rebuild, run the Verify Matches API.
Confirm that rules are no longer bypassed and matches return as expected.
What to Do if the Issue Persists
Ensure that no further over-collision tokens appear after cleanup.
Double-check that all match rules are tuned and not generating excessive tokens.
If the issue continues, share:
The Verify Matches and Matches API request/response
The rule name and environment details
References
Comments
Please sign in to leave a comment.