How to Change Entity Resolution Rules Without Breaking Production (2026)

TL;DR: Version the rule set and transformations together, replay a representative frozen corpus, compare pair and entity deltas against reviewed truth, and inspect the highest-consequence changes. Shadow the candidate version, canary a bounded source or tenant, and define rollback plus reprocessing before release. We apply new rules to new data; previously ingested records require re-ingestion to use those rules, so historical migration must be a deliberate, separately evidenced operation.

Test your matching configuration on a controlled data extract. Book a Demo · Try Tilores Studio (Free).

On this page

1. Why are matching-rule changes unusually risky?
2. How should a candidate be proved on frozen evidence?
3. Move from shadow to canary without mixing truth
4. A seven-gate rule-release process
5. Rollback must restore meaning, not only configuration
6. Which evidence must survive a rule release?
7. How do we apply a rule change in Tilores?
8. FAQ
9. Sources

Why are matching-rule changes unusually risky?

A normal application release often fails visibly: an endpoint errors, latency rises or a process crashes. A rule change can remain fast and available while connecting the wrong records. It can also split previously coherent entities or alter which candidate wins. The damage appears later in customer views, cases, analytics or automated decisions. Infrastructure health is necessary evidence, but it does not measure identity correctness.

Treat the active matching configuration as a release artifact. It includes transformations, indexes or blocking configuration, matchers, rules, thresholds, reference data and any model parameters. Hash and version the complete bundle. If a normalisation step changes while the rule ID stays the same, the effective decision system still changed and should produce a new release.

We document an important migration boundary in our FAQ: previously ingested records are not automatically updated when new matching rules are added. New data follows the new rules, while existing records must be re-ingested with their original record IDs to apply the change. That means rollout for new events and controlled historical reprocessing are related but distinct operations.

How should a candidate be proved on frozen evidence?

Replay current and candidate configurations against the same versioned corpus. Include a held-out ground-truth partition, recent production samples, known incidents and source-specific edge cases. Compare more than precision and recall. Calculate pair-level links gained and lost, entity merges and splits, cluster-size changes, unresolved volume and the rules responsible for every material delta.

Rank changes by consequence. One false merge that exposes or moves a sensitive account can matter more than thousands of benign non-links. Review large cluster changes, links crossing protected source boundaries, records with conflicting stable identifiers and cases feeding consequential workflows. A net improvement in aggregate F-score does not excuse a new high-impact failure mode.

Keep the replay reproducible. Record input snapshot, schema and transformation versions, current and candidate bundles, random seeds where relevant, evaluation policy and output hashes. If the team cannot reproduce a surprising merge from those materials, it cannot safely explain or reverse the result in production.

A candidate rule set earns production exposure through reproducible replay, outcome comparison and a bounded canary.

Move from shadow to canary without mixing truth

In shadow mode, process live input through the candidate without exposing its entity result to production consumers. Compare candidate and control outcomes and investigate deltas. Shadowing reveals current data shapes and load, but it cannot prove the business effect of a changed entity because the candidate result is not yet used. That is the purpose of a bounded canary.

A canary exposes a small, explicitly selected unit such as one low-risk source, tenant or traffic partition. The Google SRE guidance frames canaries as partial, time-limited releases compared with a control and backed by rollback. For entity resolution, the canary unit must also prevent cross-boundary entity effects. If candidate and control records can merge into the same shared entity graph, the supposed small exposure may not be small.

Keep decision telemetry separate by version. Count candidate links, non-links, unresolved cases, review reasons, downstream corrections, entity-size shifts and processing behaviour. Do not average control and canary together. Promotion is a recorded decision against pre-agreed quality and operational limits, with named approval for the highest-consequence workflows.

A seven-gate rule-release process

1. Freeze the complete candidate bundle. Version transformations, matcher and rule configuration, indexes, reference data and model parameters together. Record the author, intent and expected outcome change.
2. Run rule simulation and unit cases. Verify exact boundary examples, missing fields, contradictory identifiers and locale behaviour. These tests are quick diagnostics, not a substitute for corpus evaluation.
3. Replay a frozen representative corpus. Compare current and candidate bundles on held-out truth and recent production strata. Produce pair, entity, segment and operational deltas with reproducible hashes.
4. Review consequential changes. Inspect large merges, splits, protected boundary crossings and cases feeding sensitive decisions. Record accepted changes and unresolved objections before online exposure.
5. Shadow live input. Run the candidate without serving its result. Measure live data compatibility, candidate volume, latency and divergence while keeping current production truth unchanged.
6. Canary a bounded unit. Choose an isolated low-risk partition, compare it with a control and enforce automatic stop conditions. Confirm that graph connectivity cannot spread the candidate rule beyond the intended boundary.
7. Promote or roll back with migration control. Promotion records the exact version and approval. Rollback restores the prior bundle and addresses entities already changed. Historical re-ingestion is a separately bounded job with checkpoints, reconciliation and downstream event handling.

Rollback must restore meaning, not only configuration

Reactivating the previous rule bundle stops new candidate decisions, but it may not undo entities already changed. The recovery plan must identify affected records, reverse or recompute entity membership, emit merge or split corrections, invalidate caches and reconcile downstream references. Define that procedure before canary exposure and exercise it on a non-production snapshot.

Preserve a change ledger. For each release, keep the previous and new versions, migration scope, observed deltas, approval, start and stop times, rollback criteria and actual outcome. If a later incident spans several releases, this ledger narrows the evidence without relying on memory or a mutable dashboard.

Small releases are easier to understand. Avoid combining a new data source, new normalisation library, matcher change and threshold adjustment in one deployment. When several changes are necessary, use factorial offline comparisons or sequence them behind clear checkpoints. Otherwise an improved metric cannot tell the team which change helped, and a regression cannot tell it what to reverse.

Which evidence must survive a rule release?

Treat the candidate configuration as one immutable bundle: transformations, indexes, deterministic rules, fuzzy comparers, probabilistic features, thresholds and reference data. Record its version beside replay results so a pair or entity delta can be traced to the exact logic that produced it. A single aggregate score cannot explain why one cluster merged or another split.

Keep original values beside the normalised values used in each comparison. A normalisation change can alter the candidate set even when the matcher itself is untouched. With both forms and the bundle version retained, the team can reproduce a changed decision instead of inferring its cause from a production graph after the fact.

Promotion evidence should include the frozen corpus hash, pair and entity deltas, reviewed consequential cases, shadow window, canary control and rollback result. That record turns rollback into restoration of a known decision model, not merely a deployment of yesterday’s files.

How do we apply a rule change in Tilores?

We combine deterministic, fuzzy and probabilistic matching in configurable rule sets. Teams can inspect intended behaviour with simulation before deployment, as described in our rule configuration reference. The release record should still name the complete configuration bundle and the evidence used to approve it.

New rules apply to new data. Previously ingested records are not changed automatically, so applying the candidate to history requires re-ingestion with the original record IDs. That migration is a separate controlled operation with its own replay scope, consumer checks and rollback boundary.

Our end-to-end rollout guide covers the wider cutover. For this release, the proof is specific: the candidate has been compared on frozen truth, observed in shadow, constrained in a canary and shown to restore the prior entity state when rollback is exercised.

Frequently asked questions

Can a rule change be backward compatible?

Its configuration may parse successfully while its entity outcomes change. Treat behavioural compatibility as an observed result from replay and canary evidence, not as a schema label.

Do new rules update existing entities automatically?

No. Our FAQ states that new data follows the new rules, while previously ingested records must be re-ingested with their original record IDs to apply them.

What should automatically stop a canary?

Pre-agreed limits can include unexplained protected-boundary links, large cluster changes, quality regression in a risk segment, review-queue overload, downstream correction signals or operational failure.

Is shadow traffic enough to approve a release?

No. It tests live input and divergence without exposing candidate results. A bounded canary is needed to observe downstream effects, followed by reconciliation.

What does rollback mean after entities already changed?

It includes restoring the prior rule bundle and correcting affected entity state, aliases, events, caches and consumers. Configuration rollback alone is incomplete.

Sources

1. Tilores documentation: Rules Configuration. Product-specific rule, transformation, matcher and simulation behaviour.
2. Tilores documentation: Matcher Reference. Deterministic, fuzzy and probabilistic matcher mechanics.
3. Tilores documentation: Frequently Asked Questions. Current ID stability and rule-change implications for previously ingested records.
4. Google SRE Workbook: Canarying Releases. Time-limited partial releases, control comparisons and rollback.
5. UK Government: Quality assessment in data linkage. Precision, recall, training data, clerical review limits and linkage-error assessment.
6. AWS Prescriptive Guidance: Event sourcing pattern. Immutable ordered events, replay and versioning.
7. Tilores: What an Entity Resolution Rollout Actually Looks Like in 2026. Internal context on labelled truth, parallel running and operational ownership.

The examples are operational patterns. Release thresholds and approval ownership should reflect the consequence of identity errors in the specific workflow.