Entity resolution and deduplication

An abbreviated name can identify an existing entity, a different entity, or nothing specific enough to resolve. Context and authoritative identifiers matter more than textual resemblance.

A shared family name, brand, or description is evidence of relatedness, not necessarily identity.

A graph split across duplicate nodes can lose useful context: a message mentions one spelling while a purchase or tool result points to another. Counts can also be misleading when aliases are counted separately.

The opposite error is more damaging in some domains. Merging two product variants can mix inventory or prices; merging people can attach one person’s statements to another. A resolution policy should consider the cost of a false merge as well as the cost of missed matches.

Exact-name matching detects repeated forms. Fuzzy matching tolerates spelling and word-order differences. Embedding similarity finds semantically related candidates. Each is a signal, not an identity proof: nearby vectors can describe competitors or different variants of the same product.

Type-constrained matching reduces some false positives, such as an organization named "Apple" and an object representing the fruit. It does not distinguish two people with the same name or guarantee that a broad OBJECT category contains only interchangeable products.

On Bolt, the default OntologyResolver (what resolution.strategy="composite" builds) composes these signals rather than replacing them. It puts the candidate search in Cypher, lets deterministic evidence (an exact normalized match, a declared ontology alias, an acronym expansion) settle the score before any similarity computation, and takes its aliases and per-type bands from the ontology, so a controlled vocabulary works even with embeddings switched off.

The consequence of type-constrained blocking is that a cross-typed duplicate, such as one company extracted once as ORGANIZATION and once as OBJECT, is never found. Fix the typing, usually with a sharper ontology description, rather than loosening the blocking.

Two write paths reach the same decision through the same component:

OntologyResolver is what turns two paths into one decision. When it is the configured resolver, add_entity delegates its duplicate check to the resolver, so both paths share one normalization, one blocking strategy and one set of thresholds. Any other resolver keeps the earlier embedding-similarity check for add_entity and leaves ingestion unresolved.

Resolution is an enhancement, never a gate: if a blocking query fails, the failure is logged and the mentions are stored unresolved.

A :SAME_AS edge can record a potential duplicate without collapsing the records immediately. This preserves both candidates while an application or reviewer gathers evidence.

Review needs more than a similarity score: compare descriptions, provenance, domain identifiers, and relationships. Two missing SKU values are not evidence of a shared SKU. A meaningful comparison requires both identifiers to be present and to refer to the same identifier system.

Follow Review duplicates for the implemented Bolt workflow. The pending, confirmed, or rejected state of a candidate is different from a completed merge.

A merge selects a surviving record and reconciles supported properties and relationships. It can affect every query that previously referenced either node, so the choice of primary record and handling of conflicting values matter.

An alias preserves an alternative name; it should not conceal a product variant or a separate legal entity. Do not assume that adding arbitrary metadata.aliases makes every resolver bypass similarity search. Aliases declared on an ontology entity type are different: the ontology resolver treats them as a controlled vocabulary. Use the actual alias and merge fields in the API reference.

Bolt’s resolution configuration separates an automatic-merge threshold (resolution.auto_merge_threshold, 0.90 by default) from a review threshold (resolution.review_threshold, 0.85). An ontology can override both for one entity type. Raising the automatic threshold reduces the set of candidates merged without review; moving the review threshold changes which ambiguous pairs reach the queue. The thresholds are score cutoffs, not guaranteed precision percentages.

Choose them using labeled matches and non-matches from the actual domain. A broad, low threshold is risky for similar product variants or same-name people. Per-entity deduplication controls can preserve intentionally distinct records; see Configure deduplication and Tune entity resolution.

Names need context. A company can change its name while retaining an identity, but a merger, acquisition, or subsidiary relationship may involve separate legal entities. Preserve dates and provenance when the distinction matters.

A parent company and a subsidiary should normally be modeled as related entities, not merged because they share a brand. Likewise, "Air Max" can denote a family while "Air Max 90" denotes a model. The graph can retain their relationship without asserting that they are the same thing.

Evaluate both accepted and rejected matches against a labeled sample. Review queue size alone does not establish quality: a small queue might mean accurate resolution, an overly narrow candidate search, or excessive automatic merging.

Useful observations include false merges, missed aliases, disagreement by entity type, and time spent reviewing candidates. Choose workload-specific targets and record how the sample was labeled. No universal rejection-rate or queue-size percentage establishes that a deployment is healthy. The evaluation harness’s resolution dimension scores the configured resolver against labeled clusters; see Evaluate memory quality.

Use stable domain identifiers where available, retain provenance, and keep distinct variants separate. Treat broad names as ambiguous until a source resolves them. Adjust thresholds after reviewing representative matches and non-matches.

A shared memory graph benefits from consistent naming, but consistency is not a reason to merge unrelated records. Periodic review should include automatic decisions as well as flagged candidates.