What tasks should I run after adding a new match rule?

After I add a new match rule to an entity type, do I still need to run the Cleanup Matches Task along with Rebuild Match Table, Potential Matches Reindex, and Reindex Data?

Answer

No. The Cleanup Matches Task is not required when you only add a new match rule; run the Rebuild Match Table task so existing records are evaluated against the new rule.

The Cleanup Matches Task removes potential matches, auto not-matches, and grouping matches from the MATCHES table for the match group URIs you pass in. A newly added rule has no stored matches yet, so the task has nothing to remove. It applies when you change or remove an existing rule, where matches created by the old logic are still stored. Even then, it is a recommended optimization for tenants with a large volume of potential matches, because it drops the outdated pairs faster than the rebuild would.

Which task is needed when

After adding a new rule, only the Rebuild Match Table task is required; the other three depend on what else changed.

Endpoints and request examples

Replace {environment} with your environment host and {tenantId} with your tenant ID. Every request needs an Authorization: Bearer <access_token> header and Content-Type: application/json.

Rebuild Match Table. Requires the ROLE_ADMIN_TENANT role. entityType is optional (all types are processed if omitted), and distributed=true with taskPartsCount splits the work across API nodes. No body rebuilds the whole entity type.

POST https://{environment}.reltio.com/reltio/api/{tenantId}/rebuildmatchtable?entityType=Organization&distributed=true&taskPartsCount=8

To rebuild only specific entities, send their URIs as the body:

["entities/aaaaaaa", "entities/bbbbbbb"]

Cleanup Matches. Requires Execute privileges. entityType and rules are required; rules lists the URIs of the match groups whose matches should be deleted. The task runs well with eight or more parts.

POST https://{environment}.reltio.com/reltio/api/{tenantId}/cleanupMatches

{
  "entityType": "Organization",
  "rules": [
    "configuration/entityTypes/Organization/matchGroups/<ChangedOrRemovedRuleName>"
  ],
  "distributed": true,
  "taskPartsCount": 8
}

The response describes the created job and reports counters such as numberOfProcessedObjects and totalNumberOfDeletedMatches.

Potential Matches Reindex. Requires a tenant admin role. The optional filter parameter limits the reindex to entities that match a condition.

POST https://{environment}.reltio.com/reltio/api/{tenantId}/rebuildpmcounters?distributed=true&taskPartsCount=4

Reindex Data. Requires a tenant admin role. Set enableSeparateIndexing=true only when reindexing the entire tenant, never for a subset of entities. With it set, the task builds a new index, swaps it in on completion, and triggers the Potential Matches Reindex automatically.

POST https://{environment}.reltio.com/reltio/api/{tenantId}/reindex?distributed=true&taskPartsCount=8&enableSeparateIndexing=true

Recommended order

For a purely additive rule, run Rebuild Match Table and nothing else unless a check below applies.

1. If the same change also altered attributes, sources, cleanse configuration, lookup mappings or MatchFieldUris, run Reindex Data first. It does not rebuild match tables, so a rebuild must follow it.
2. If the same change also modified or removed existing match rules, run Cleanup Matches for those rule URIs before the rebuild, so the rebuild does not have to remove the outdated matches itself.
3. Run Rebuild Match Table for the entity type.
4. If potential match counters or the Hub view look inconsistent afterward, run Potential Matches Reindex. Skip this step if you used enableSeparateIndexing=true on Reindex Data, because it runs automatically.

Do not update the tenant business configuration while a Reindex Data task is running.