Reading tools and contents
4 min
Production RAG & GraphRAG

Chapter 3 of 10

Entity resolution and graph construction

Index construction

About 4 minutes · includes examples, an exercise, and references

Chapter at a glance

  • •Keep source units, mentions, and canonical entities as distinct addressable objects.
  • •Aggregate parallel evidence for ranking without losing individual provenance.
  • •Version edge-weight meaning, time window, and all construction inputs.

Graph construction begins after extraction, not during it. Its job is to turn source-scoped mentions and claims into a queryable, versioned graph without erasing uncertainty. The central challenge is entity resolution because community structure, node degree, local search, and path explanations all depend on identity. One over-merged hub can connect unrelated domains and dominate every retrieval; one fragmented entity can hide evidence across aliases.

Represent three identities: source units, mentions, and canonical entities. A mention belongs to exactly one source location. A resolution decision links it to a canonical entity with method, evidence, score, model, and review state. The canonical entity aggregates names and source claims but does not replace them. Unknown or ambiguous mentions can remain unresolved and still be retrievable through lexical and dense indexes.

Candidate generation can use exact identifiers, normalized aliases, type, surrounding entities, document metadata, and vector similarity. Candidate scoring should include negative evidence and ontology constraints. A Project mention should not resolve to a Person merely because their labels match. Cross-document links deserve stricter evidence than within-document coreference. Store the top candidates and abstention reason so future improvements can revisit decisions.

Do not collapse every extracted relation into a single weighted edge. Preserve relation type, direction, source claim identifiers, valid time, and extraction status. A serving projection may aggregate parallel evidence into an edge weight, but the evidence set remains addressable. Weight can mean mention frequency, distinct-document count, source trust, recency, or model confidence; these meanings are not interchangeable. Name and version the formula.

Graph construction should be deterministic from an index manifest. Inputs include document release, extraction outputs, resolver model, ontology mapping, filters, and aggregation rules. Outputs include entity and relationship tables, source-unit links, claim tables, embeddings, and quality reports. The official GraphRAG output model distinguishes documents, text units, entities, relationships, communities, and community reports; preserving those roles makes query behavior inspectable.

Control degree explosions. Generic organizations, countries, common technologies, and extraction artifacts can become hubs. Some hubs are real and valuable; others result from over-resolution or uninformative relations. Track degree by entity type and relation, compare releases, and examine sudden changes. Cap or down-weight only through documented query policy, not by deleting inconvenient evidence.

Deduplication operates at several levels. Duplicate documents should be detected by digest and near-duplicate analysis. Duplicate source units may arise from overlap. Duplicate claims require normalized subject, relation, object, time, polarity, and evidence comparison. Two sources making the same claim are separate evidence, not necessarily duplicates. Aggregate them for ranking while retaining distinct provenance.

Temporal construction avoids timeless topology. A relationship may be valid only during an interval, while the extraction and transaction have different dates. Build current and historical projections or require time filters in traversals. Community detection over all historical edges may join entities that were never connected simultaneously. State the temporal window used for each index.

Security labels must propagate before aggregation. A public and confidential mention may resolve to one canonical entity, but an unauthorized query must not infer confidential relationships, aliases, counts, or community membership. Build security-compatible projections or compute views under policy. Never use an unrestricted entity description as context merely because the selected source unit was authorized.

Evaluate construction with resolution benchmarks, orphan and duplicate rates, type violations, degree distributions, connected-component changes, source coverage, evidence-per-edge, and temporal consistency. Then run retrieval tests: a beautiful topology that does not improve answers is still an unsuccessful index.

Key points

  • Keep source units, mentions, and canonical entities as distinct addressable objects.
  • Aggregate parallel evidence for ranking without losing individual provenance.
  • Version edge-weight meaning, time window, and all construction inputs.
  • Propagate authorization through resolution and aggregation, not only final text retrieval.

Evidence-preserving edge aggregation

Read the expected behavior in the surrounding walkthrough, then copy and run this reference implementation.

Evidence-preserving edge aggregationpython
from collections import defaultdict

def aggregate_edges(claims):
    grouped = defaultdict(list)
    for claim in claims:
        key = (claim["subject"], claim["predicate"], claim["object"], claim["polarity"])
        grouped[key].append(claim)

    return [
        {
            "edge": key,
            "distinct_documents": len({c["document"] for c in evidence}),
            "evidence_ids": [c["id"] for c in evidence],
        }
        for key, evidence in grouped.items()
    ]

Worked examples

Toy

Two Mercurys

One corpus discusses the planet and a software project with the same name.

Type, neighboring mentions, and document domain keep them separate. Ambiguous short mentions stay unresolved rather than creating one high-degree Mercury hub.

  • Candidate evidence
  • Type constraint
  • Abstention path

System

Security-scoped canonical entity

Public filings and restricted investigations describe the same organization.

Identity may be shared in a protected control layer, while public and restricted serving projections expose only permitted descriptions, edges, and counts.

  • Identity visibility
  • Aggregated metadata leakage
  • Projection reproducibility

Exercise

Construct a versioned evidence graph

Build canonical entities and typed edges from extracted mentions in at least two documents.

  1. Keep mention-to-source and mention-to-entity links.
  2. Implement an abstaining resolver.
  3. Aggregate evidence with a named weight formula.
  4. Report degree, orphan, duplicate, and type anomalies.

Success criteria

  • A mistaken merge can be reversed without re-extraction.
  • Every serving edge lists its evidence claims.
  • Temporal and security scopes are declared.
  • The same manifest reproduces the same graph.

Reflect: Which aggregation makes the graph look simpler while hiding a decision you will later need to audit?

References and further reading