GraphRAG Entity Resolution Before Retrieval

GraphRAG entity resolution decides whether “IBM,” “International Business Machines,” and “Big Blue” become one node—and whether two different people named Alex remain separate. That identity decision changes communities, paths, summaries, and every answer retrieved from the graph.

Resolve conservatively before retrieval, retain provenance through every merge, and measure the graph delta rather than judging only fluent answers. The alias cluster below is a worked fixture, not a claim about a production knowledge base.

GraphRAG entity resolution is an identity contract

A mention is a span in a source. An entity is a canonical record. A node is a graph representation of that record.

Keep the three identifiers distinct so a resolver can change without rewriting source history. The canonical record should carry type, normalized name, stable key, alias evidence, source spans, resolver version, decision state, and any external authority IDs.

The Microsoft GraphRAG project describes a structured approach that extracts a knowledge graph and community summaries for retrieval. GraphRAG entity resolution sits before those graph products. If duplicate mentions become separate nodes, communities fragment. If unrelated mentions merge, edges and summaries acquire false relationships that later ranking cannot repair.

Start with a tiny gold slice that includes aliases, abbreviations, renamed organizations, transliterations, shared personal names, parent/subsidiary pairs, and genuinely unknown mentions. Knowledge graph deduplication is only one outcome; “do not merge yet” is equally important. Every automated merge must be reversible by replaying the canonicalization map against immutable mention evidence.

Read this cluster from the sources inward: names propose a path, evidence authorizes a canonical assignment, and ambiguity remains a visible state instead of becoming an invented certainty.

Build candidate pairs from bounded evidence

Do not compare every mention with every entity. Block candidates by compatible type, normalized tokens, acronym, external identifier, geography, temporal overlap, or source neighborhood. Record which blocker proposed the pair; otherwise a missed match has no diagnostic path. Exact authority IDs can be strong evidence, but recycled identifiers and source errors still need conflict handling.

Score name similarity, alias history, type compatibility, temporal consistency, shared identifiers, and relational context as separate features. Entity canonicalization should not collapse them into one opaque confidence without retaining the inputs. A name match can propose a candidate; it should not overrule contradictory geography or overlapping employment for two people. Missing context means abstain, not assume.

Candidate records need identity merge rules covers the operational pattern: merge, link, or hold for review based on explicit evidence. For GraphRAG entity resolution, add graph contamination severity. A high-degree merge can rewrite thousands of paths, so the threshold or human review requirement should rise with the projected blast radius. Compute that radius before committing the canonical map.

Runnable artifact: The alias fixture normalizes punctuation and Unicode, maps three organizational aliases to one stable key, preserves an unknown, and proves repeatability. It is deliberately conservative and should be extended with type and temporal conflicts.

Save this worked fixture as graphrag-alias-clusters.test.mjs and run node graphrag-alias-clusters.test.mjs. Expected final line: PASS: 10 entity assertions.

import assert from "node:assert/strict";
const norm=s=>s.normalize("NFKD").toLowerCase().replace(/[^a-z0-9]/g,"");
const catalog=new Map([["internationalbusinessmachines","ibm"],["ibm","ibm"],["bigblue","ibm"],["graph rag","graphrag"]].map(([a,b])=>[norm(a),b]));
const resolve=name=>catalog.get(norm(name)) ?? null;
let n=0;const check=fn=>{fn();n++};
check(()=>assert.equal(resolve("IBM"),"ibm"));
check(()=>assert.equal(resolve("I.B.M."),"ibm"));
check(()=>assert.equal(resolve("International Business Machines"),"ibm"));
check(()=>assert.equal(resolve("Big Blue"),"ibm"));
check(()=>assert.equal(resolve("Graph RAG"),"graphrag"));
check(()=>assert.equal(resolve("unknown"),null));
check(()=>assert.equal(resolve("IBM "),"ibm"));
check(()=>assert.equal(norm("Éntity"),"entity"));
check(()=>assert.equal(new Set([...catalog.values()].filter(x=>x==="ibm")).size,1));
check(()=>assert.equal(resolve("IBM"),resolve("Big Blue")));
assert.equal(n,10);console.log("PASS: 10 entity assertions");

Distinguish merge, alias, and relationship

“Acme,” “Acme Holdings,” and “Acme Colombia” might be aliases, a parent company, and a regional subsidiary. A resolver that merges all similar names destroys the very relationship the graph should expose. Model merge as identity equality, alias as another surface form for the same identity, and edge as a relationship between different identities. Keep mention-to-entity assignments separate from entity-to-entity edges.

The GraphRAG paper presents the indexing and community-based retrieval approach. The production lesson is that extraction uncertainty propagates into graph structure. GraphRAG entity resolution should attach provenance to nodes and edges so a reviewer can return from a surprising community statement to the mention assignments that created it.

Create contradiction fixtures: same name/different type, same type/different countries, parent and subsidiary sharing tokens, a person who changed employers, and a renamed organization. The expected result can be distinct nodes connected by a typed edge. A resolver earns trust by refusing a seductive merge when evidence supports relationship instead. That distinction often improves graph retrieval quality more than tuning a downstream similarity threshold.

Evaluate clusters before answers

On the labeled slice, report pairwise precision and recall, cluster metrics, type-specific errors, abstention rate, and projected edge rewrites. Weight false merges more heavily where they create cross-tenant, cross-person, or high-degree contamination. Keep a naive normalized-name baseline and a deliberately overaggressive baseline. The candidate resolver must beat both for the right reasons.

Then measure graph deltas: node count, edge count, component count, degree distribution, community membership churn, path changes, orphan mentions, and summary invalidations. GraphRAG entity resolution can improve duplicate counts while making a key community worse. Review the largest structural changes and a seeded sample of low-confidence non-changes.

Retrieval evaluation comes after structural proof. Use questions whose evidence spans aliases, questions that distinguish similarly named entities, and questions that require parent/subsidiary separation. Compare candidate paths and source IDs, not answer prose alone. Late interaction retrieval and hybrid search RRF can retrieve textual evidence alongside graph results; preserve lineage so resolution errors are not mislabeled as ranking failures.

Version summaries with their canonical map

Community summaries are derived data. Store resolver version, graph snapshot, community algorithm and parameters, member entity IDs, source document generations, summarizer identity, and creation time. A merge or split invalidates every summary whose membership or supporting paths changed. Reuse is allowed only when the complete dependency hash remains equal.

This is where community summary drift becomes measurable. Compare entity membership, claim-source coverage, unsupported statements, and question performance across resolver versions. A fluent unchanged summary can still be stale after identities split. RAG citations that survive document change supplies the corresponding source-generation discipline: the summary should cite immutable evidence, while the interface can resolve current readable versions.

Do not overwrite old canonical IDs casually. Maintain redirects for confirmed merges and tombstones for splits, with migration logs. External caches, feedback records, and evaluation fixtures may refer to prior IDs.

GraphRAG entity resolution needs a migration plan that can translate those references or declare them ambiguous. Stable identity is a product surface even when only internal retrieval currently consumes it.

Put high-blast-radius decisions in review

Review queues should prioritize expected harm, not just scores near a threshold. Surface candidate mentions, source excerpts, types, temporal evidence, proposed cluster, conflicting features, degree and community impact, and the reversible action. Reviewers need merge, link, keep separate, defer, and correct-source options. Their decisions become labeled evidence only after quality checks.

Batching similar cases can improve consistency, but hide the model's proposed decision until the reviewer has inspected evidence if anchoring is a concern. Measure inter-reviewer agreement on ambiguous policies and revise the rulebook before merely adding more labels. Sensitive entities may require access-scoped review views and redacted exports.

GraphRAG entity resolution also needs deletion and correction workflows. If a source is removed, retract its mention evidence and recompute any decision that depended on it. If a human splits a cluster, add a constraint preventing automatic remerge until the policy version explicitly supersedes it. Manual correction is not a permanent truth without provenance; it is another versioned decision in the identity ledger.

Publish an identity and graph-diff receipt

The release packet should include corpus snapshot, mention extractor, type system, blockers, features, thresholds, model and prompt identities, authority sources, review policy, labeled slice, cluster metrics, high-impact errors, graph deltas, invalidated communities, retrieval cases, and rollback pointer. GraphRAG entity resolution then becomes independently inspectable from downstream generation.

The GraphRAG query overview documents query modes in the active project and should be pinned to the version you deploy. Test local and global query behavior on the shadow graph, but retain the exact entities, relationships, communities, and text units each query used. A final answer score cannot locate an identity defect without that trace.

Refresh the receipt when the corpus, extractor, resolver, graph builder, community detector, summarizer, or query engine changes. The strongest result is not the fewest nodes. It is a graph where aliases meet when evidence proves identity, similarly named entities remain separate when evidence conflicts, every structural decision points back to sources, and retrieval can explain which canonical path supported its answer.