1. Reltio Support
  2. Knowledge Base
  3. Match/Merge

How to Run the RebuildGrouping Task (Advanced / Segmented Grouping)

Gloria
Updated

Overview

The RebuildGrouping task recalculates all grouping associations and recreates hierarchy entities (e.g., ImmediateParent, DomesticParent, GlobalParent) based on the current L3 grouping rules. It is a two-phase background job:

Phase

Task Type

What It Does

Typical Throughput

Phase 1

RebuildGroupingUpdateDataPhaseTask

Updates entity data and grouping structures

~1,000–1,500/sec per task part

Phase 2

RebuildGroupingMatchSyncPhaseTask

Pairwise match evaluation + hierarchy construction

~14–20/sec per task part

Phase 2 auto-starts when all Phase 1 parts complete. Do not manually submit Phase 2.

 

When to Run RebuildGrouping

Run this task when:

  • Grouping rules are newly enabled or modified in L3 configuration

  • Grouping match rules (attributes, operators, token classes) are changed

  • After remediating a broken grouping configuration (e.g., nested attribute misconfiguration)

  • After hard-deleting hierarchy entities and re-enabling grouping

 

Prerequisites

Before triggering the task, verify:

1. Advanced Grouping is correctly configured in the physical tenant config:

GET https://{env}.reltio.com/reltio/tenants?tenantId={tenantId}

Correct configuration:

"groupingConfig": {
    "enabled": true,
    "version": "v2"
}

2. Matching strategy is active:

"matchingConfiguration": {
    "strategy": "INCREMENTAL_V2"
}

 

 

How to Trigger the Task

API Request

POST https://{env}.reltio.com/reltio/api/{tenantId}/rebuildGrouping?distributed=true&taskPartsCount=<taskParts>&force=true

Query Parameters

Parameter

Required

Description

Default

distributed

No

Runs the task in distributed mode — creates multiple parallel task parts

false

taskPartsCount

No

Number of parallel task parts. Recommended: 8–16 for large tenants; adjust down for smaller ones

2

force

No

Forces the rebuild even if the task believes grouping is already up to date

false

Recommendation: Always use distributed=true for production tenants. Omitting it runs the task as a single-part job, which is significantly slower.

Internal rebuildGroupingOptions (set automatically by the platform)

These parameters appear in the task response under parameters.rebuildGroupingOptions. They are not set via query parameters — they are controlled internally or via the request body.

Option

Type

Description

skipUpdateDataPhase

boolean

If true, skips Phase 1. Default: false

skipVersionCheck

boolean

If true, bypasses version checks during processing. Default: true

forceAttributesUpdate

boolean

If true, forces attribute updates during Phase 1. Default: true

forceMatching

boolean

If true, forces match re-evaluation in Phase 2. Default: true

forceCalcSyncDelta

boolean

Controls delta calculation during sync. Default: false

getUrisFromGroupingDocuments

boolean

Controls URI sourcing strategy. Default: false

memberIdsToRebuild

array

Limit rebuild to specific member entity IDs. Default: [] (all)

groupingDocumentIdsToRebuild

array

Limit rebuild to specific grouping document IDs. Default: [] (all)

entitiesBatchSize

integer/null

Override entity batch size. Default: null (platform default)

documentsBatchSize

integer/null

Override document batch size. Default: null (platform default)

 

How to Monitor the Task

Check active tasks:

GET https://{env}.reltio.com/reltio/api/{tenantId}/tasks

Check task history (completed/failed):

GET https://{env}.reltio.com/reltio/api/{tenantId}/tasks/history

Check task group (all distributed parts):

GET https://{env}.reltio.com/reltio/tasks/groups/{groupId}

Key fields to monitor in the task response:

{
  "type": "...RebuildGroupingUpdateDataPhaseTask",
  "status": "COMPLETED",
  "throughput": 1323.07,
  "duration": "1h 9m 40s",
  "currentState": {
    "numberOfProcessedObjects": 90122624,
    "numberOfFailedToPublishEvents": 0
  }
}

Field

What to Look For

status

COMPLETED for all parts = success

throughput

Phase 1: expect ~1,000+/sec per part. Phase 2: expect ~14–20/sec per part

numberOfFailedToPublishEvents

Should be 0

error

If FAILED, check this field for root cause

How to Verify Success

Once Phase 2 completes, confirm hierarchy entities were created:

GET https://{env}.reltio.com/reltio/api/{tenantId}/entities/_total
    ?filter=(equals(type,'configuration/entityTypes/ImmediateParent'))

GET https://{env}.reltio.com/reltio/api/{tenantId}/entities/_total
    ?filter=(equals(type,'configuration/entityTypes/DomesticParent'))

GET https://{env}.reltio.com/reltio/api/{tenantId}/entities/_total
    ?filter=(equals(type,'configuration/entityTypes/GlobalParent'))

All three should return non-zero counts.

Note: ES index lag is normal post-rebuild. If advanced search shows "Missing Value" for a parent reference but the profile view shows it correctly, run a scoped reindex:

POST https://{env}.reltio.com/reltio/api/{tenantId}/reindex
     ?entityType=configuration/entityTypes/ImmediateParent
     &updateEntities=false

updateEntities=false refreshes only the ES index — no rematching or history changes.

 

Stopping or Pausing the Task

Stop:

PUT https://{env}.reltio.com/reltio/api/{tenantId}/tasks/{taskId}/_stop

 

 

Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.

Articles in this section

See more