Design GraphRAG: Chunk/Entity/Relationship Modeling, Retrieval, Context Assembly, Provenance, and Evaluation

GraphRAG is often described as “vector search plus a graph plus an LLM,” which hides the engineering contract. AtlasMart’s question “Which camera should I use for wildlife on remote trails at night, and why?” requires retrieval, provenance, entity resolution, relationship expansion, context budgeting and evaluation before any text generator is involved. The mandatory lab stops at a deterministic evidence packet so it remains free/local and so retrieval quality can be tested independently from generation quality.

Learning outcomes

Lab contract and exact assumptions

Direct-entry setup

The Chapter 22 fixture already includes two KnowledgeDocument nodes and four Chunk nodes with deterministic embeddings, FROM_DOCUMENT/NEXT_CHUNK/MENTIONS relationships and a chunk vector index. This mirrors the lexical-graph concepts in the official GraphRAG tooling without requiring a paid LLM/entity extractor.

CYPHER 25
// Disposable Chapter 22 fixture. Safe to rerun after the cleanup block.
CREATE CONSTRAINT ch22_product_id IF NOT EXISTS
FOR (p:Product) REQUIRE p.productId IS UNIQUE;
CREATE CONSTRAINT ch22_category_id IF NOT EXISTS
FOR (c:Category) REQUIRE c.categoryId IS UNIQUE;
CREATE CONSTRAINT ch22_store_id IF NOT EXISTS
FOR (s:Store) REQUIRE s.storeId IS UNIQUE;
CREATE CONSTRAINT ch22_doc_id IF NOT EXISTS
FOR (d:KnowledgeDocument) REQUIRE d.documentId IS UNIQUE;
CREATE CONSTRAINT ch22_chunk_id IF NOT EXISTS
FOR (c:Chunk) REQUIRE c.chunkId IS UNIQUE;

MERGE (cam:Category {categoryId:'CAT-22-CAM'}) SET cam.name='Cameras', cam.labTag='ch22'
MERGE (out:Category {categoryId:'CAT-22-OUT'}) SET out.name='Outdoor', out.labTag='ch22'
MERGE (sec:Category {categoryId:'CAT-22-SEC'}) SET sec.name='Security', sec.labTag='ch22'
MERGE (acc:Category {categoryId:'CAT-22-ACC'}) SET acc.name='Accessories', acc.labTag='ch22'
MERGE (st:Store {storeId:'ST-22-CENTRAL'}) SET st.name='AtlasMart Central', st.labTag='ch22';

UNWIND [
 {id:'P-2201',name:'Trail Camera Pro',description:'Weatherproof wildlife trail camera with infrared night vision and long battery life',tags:['wildlife','trail','infrared','outdoor'],active:true,cat:'CAT-22-CAM',catCode:'CAMERA',region:'CENTRAL',qty:5,featured:true, emb:[0.95,0.85,0.25,0.05,0.10,0.90,0.05,0.05]},
 {id:'P-2202',name:'Trail Camera Mini',description:'Compact wildlife camera for trails, gardens, and backyard monitoring',tags:['wildlife','trail','compact'],active:true,cat:'CAT-22-CAM',catCode:'CAMERA',region:'CENTRAL',qty:0,featured:false,emb:[0.90,0.80,0.15,0.05,0.05,0.82,0.05,0.05]},
 {id:'P-2203',name:'Indoor Security Camera',description:'Wi-Fi home security camera with motion alerts and night vision',tags:['security','indoor','night vision'],active:true,cat:'CAT-22-SEC',catCode:'SECURITY',region:'CENTRAL',qty:7,featured:false,emb:[0.92,0.10,0.95,0.02,0.05,0.05,0.05,0.05]},
 {id:'P-2204',name:'Trail Running Hydration Vest',description:'Lightweight hydration vest for long trail runs and mountain races',tags:['running','trail','hydration'],active:true,cat:'CAT-22-OUT',catCode:'OUTDOOR',region:'CENTRAL',qty:11,featured:false,emb:[0.02,0.88,0.02,0.95,0.10,0.10,0.05,0.02]},
 {id:'P-2205',name:'Action Camera 4K',description:'Water-resistant action sports camera for cycling, hiking, and travel',tags:['action','sports','camera'],active:true,cat:'CAT-22-CAM',catCode:'CAMERA',region:'CENTRAL',qty:3,featured:true,emb:[0.90,0.45,0.20,0.10,0.95,0.15,0.05,0.03]},
 {id:'P-2206',name:'Wildlife Field Guide',description:'Illustrated guide to birds and mammals for outdoor observation',tags:['wildlife','book','outdoor'],active:true,cat:'CAT-22-OUT',catCode:'OUTDOOR',region:'CENTRAL',qty:6,featured:false,emb:[0.05,0.55,0.05,0.05,0.05,0.95,0.05,0.02]},
 {id:'P-2207',name:'Solar Trail Charger',description:'Solar charger for outdoor cameras, sensors, and trail equipment',tags:['solar','trail','charger'],active:true,cat:'CAT-22-ACC',catCode:'ACCESSORY',region:'CENTRAL',qty:0,featured:false,emb:[0.08,0.75,0.10,0.05,0.10,0.10,0.95,0.02]},
 {id:'P-2208',name:'Refurbished Trail Camera',description:'Older trail camera unit retained for support reference only',tags:['trail','camera','refurbished'],active:false,cat:'CAT-22-CAM',catCode:'CAMERA',region:'ARCHIVE',qty:2,featured:false,emb:[0.88,0.68,0.15,0.05,0.05,0.60,0.05,0.95]}
] AS row
MERGE (p:Product {productId:row.id})
SET p.name=row.name, p.description=row.description, p.tags=row.tags,
    p.active=row.active, p.categoryCode=row.catCode, p.region=row.region,
    p.featured=row.featured, p.embedding=row.emb,
    p.embeddingModel='atlasmart-deterministic-v1', p.embeddingVersion='2026-09-lab',
    p.labTag='ch22'
WITH row,p
MATCH (cat:Category {categoryId:row.cat}), (st:Store {storeId:'ST-22-CENTRAL'})
MERGE (p)-[:IN_CATEGORY]->(cat)
MERGE (p)-[stock:STOCKED_AT]->(st)
SET stock.quantity=row.qty, stock.labTag='ch22';

MERGE (d1:KnowledgeDocument {documentId:'DOC-22-TRAILCAM'})
SET d1.title='Trail Camera Pro field manual', d1.uri='atlasmart://manuals/P-2201', d1.version='2026.09', d1.labTag='ch22'
MERGE (d2:KnowledgeDocument {documentId:'DOC-22-SECURITY'})
SET d2.title='Camera selection guide', d2.uri='atlasmart://guides/camera-selection', d2.version='2026.09', d2.labTag='ch22';

UNWIND [
 {id:'CHK-2201',doc:'DOC-22-TRAILCAM',seq:1,text:'Trail Camera Pro is weatherproof and optimized for wildlife monitoring on outdoor trails.',emb:[0.96,0.86,0.12,0.02,0.02,0.94,0.02,0.02],products:['P-2201'],cats:['CAT-22-CAM']},
 {id:'CHK-2202',doc:'DOC-22-TRAILCAM',seq:2,text:'Infrared night vision records wildlife without visible illumination and battery life is designed for field deployment.',emb:[0.88,0.72,0.25,0.02,0.02,0.90,0.02,0.02],products:['P-2201'],cats:['CAT-22-CAM']},
 {id:'CHK-2203',doc:'DOC-22-SECURITY',seq:1,text:'Indoor Security Camera focuses on Wi-Fi motion alerts and indoor night vision rather than outdoor wildlife use.',emb:[0.84,0.08,0.96,0.02,0.02,0.06,0.02,0.02],products:['P-2203'],cats:['CAT-22-SEC']},
 {id:'CHK-2204',doc:'DOC-22-SECURITY',seq:2,text:'Choose an outdoor trail camera when weather resistance and wildlife observation matter; choose indoor security cameras for home alerting.',emb:[0.90,0.68,0.55,0.02,0.02,0.72,0.02,0.02],products:['P-2201','P-2203'],cats:['CAT-22-CAM','CAT-22-SEC']}
] AS row
MERGE (c:Chunk {chunkId:row.id})
SET c.seq=row.seq, c.text=row.text, c.embedding=row.emb,
    c.embeddingModel='atlasmart-deterministic-v1', c.embeddingVersion='2026-09-lab', c.labTag='ch22'
WITH row,c
MATCH (d:KnowledgeDocument {documentId:row.doc})
MERGE (c)-[:FROM_DOCUMENT]->(d)
WITH row,c
UNWIND row.products AS pid
MATCH (p:Product {productId:pid})
MERGE (c)-[:MENTIONS]->(p)
WITH row,c
UNWIND row.cats AS cid
MATCH (cat:Category {categoryId:cid})
MERGE (c)-[:MENTIONS]->(cat);

MATCH (a:Chunk {chunkId:'CHK-2201'}),(b:Chunk {chunkId:'CHK-2202'}) MERGE (a)-[:NEXT_CHUNK]->(b);
MATCH (a:Chunk {chunkId:'CHK-2203'}),(b:Chunk {chunkId:'CHK-2204'}) MERGE (a)-[:NEXT_CHUNK]->(b);

CREATE FULLTEXT INDEX ch22_catalog_ft IF NOT EXISTS
FOR (p:Product) ON EACH [p.name,p.description,p.tags]
OPTIONS {indexConfig:{`fulltext.analyzer`:'english',`fulltext.eventually_consistent`:false}};

CREATE VECTOR INDEX ch22_product_vector IF NOT EXISTS
FOR (p:Product)
ON p.embedding
WITH [p.active,p.categoryCode,p.region]
OPTIONS {indexConfig:{
  `vector.dimensions`:8,
  `vector.similarity_function`:'cosine',
  `vector.quantization.type`:'scalar',
  `vector.default_search_expansion_factor`:1.5
}};

CREATE VECTOR INDEX ch22_chunk_vector IF NOT EXISTS
FOR (c:Chunk)
ON c.embedding
WITH [c.embeddingVersion,c.seq]
OPTIONS {indexConfig:{
  `vector.dimensions`:8,
  `vector.similarity_function`:'cosine'
}};

CALL db.awaitIndexes(300);

1. Model retrieval units separately from domain entities

A Product is a domain entity; a Chunk is a retrieval/evidence unit; a KnowledgeDocument is a provenance container. Conflating them creates difficult lifecycle problems: product facts change independently from documentation text, chunk size/embedding changes during retrieval experiments, and source documents need version/URI metadata for audit.

2. Retrieve chunks, then expand evidence—not the other way around

The query first performs vector SEARCH on Chunk with an embedding-version filter. It then follows provenance/entity relationships and returns a structured evidence packet. This keeps the expensive candidate stage bounded and makes every returned statement traceable to a chunk and source.

CYPHER 25
MATCH (chunk:Chunk)
  SEARCH chunk IN (
    VECTOR INDEX ch22_chunk_vector
    FOR $qvec
    WHERE chunk.embeddingVersion = '2026-09-lab'
    LIMIT 3
  ) SCORE AS vectorScore
MATCH (chunk)-[:FROM_DOCUMENT]->(doc:KnowledgeDocument)
OPTIONAL MATCH (chunk)-[:MENTIONS]->(entity)
WITH chunk,doc,vectorScore,
     collect(DISTINCT CASE
       WHEN entity:Product THEN {kind:'Product',id:entity.productId,name:entity.name}
       WHEN entity:Category THEN {kind:'Category',id:entity.categoryId,name:entity.name}
       ELSE NULL END) AS entities
RETURN {
  chunkId:chunk.chunkId,
  text:chunk.text,
  vectorScore:vectorScore,
  source:{documentId:doc.documentId,title:doc.title,uri:doc.uri,version:doc.version},
  entities:[e IN entities WHERE e IS NOT NULL]
} AS evidence;
// This returns a retrieval/context packet, not an LLM answer.

3. Context assembly is a budgeted data product

A production context assembler should deduplicate chunks, optionally add adjacent NEXT_CHUNK context, fetch authoritative graph facts, enforce tenant/security rules, and cap tokens/bytes. It should not dump an unbounded neighborhood into the model. Every context item should retain source and relationship provenance.

{
  "queryId":"rag-2026-09-09-001",
  "embedding":{"model":"atlasmart-deterministic-v1","version":"2026-09-lab"},
  "retrieval":{"index":"ch22_chunk_vector","sourceK":3,"strategy":"vector+graph"},
  "evidence":[
    {
      "chunkId":"CHK-2201",
      "source":{"documentId":"DOC-22-TRAILCAM","uri":"atlasmart://manuals/P-2201","version":"2026.09"},
      "entities":[{"kind":"Product","id":"P-2201"},{"kind":"Category","id":"CAT-22-CAM"}],
      "text":"...exact retrieved chunk text..."
    }
  ],
  "graphFacts":[{"productId":"P-2201","storeId":"ST-22-CENTRAL","quantity":5}],
  "policy":{"tenant":"demo","authorizationChecked":true}
}

4. Provenance is not decoration

If a generated answer says “Trail Camera Pro is weatherproof,” the system should be able to point to CHK-2201 and its document URI/version. If it says “five units are available,” that evidence comes from the live STOCKED_AT relationship, not the manual. Keeping provenance classes separate prevents a stale document from being mistaken for transactional inventory truth.

5. Evaluate retrieval and generation separately

GraphRAG can fail even if the final prose sounds plausible. Build evaluation layers. Retrieval metrics ask whether the needed chunks/entities appeared. Context metrics ask whether evidence was authorized, deduplicated and provenance-complete. If a generator is added, answer metrics ask whether claims are supported/cited and whether unsupported statements/hallucinations appear. Latency/cost metrics span all stages.

6. Controlled failure injection

Use reversible failures that exercise the retrieval contract, not destructive production chaos. Examples: remove one chunk embedding, query with wrong dimension, temporarily point the service to a non-existent index name, mark an embeddingVersion filter that matches nothing, duplicate a chunk, or remove a MENTIONS edge. For each, record expected signal, user fallback and reset.

7. Embedding/index migration and rollback

Never overwrite model metadata and hope. Write new embeddings under a new property/version or maintain a migration strategy, populate a new vector index, run the frozen GraphRAG evaluation suite, compare cost/recall/context/answer metrics, switch configuration, and keep the old path until rollback confidence expires. The graph model and provenance IDs should remain stable across encoder changes where possible.

8. Optional official GraphRAG package vs mandatory manual path

Neo4j’s current first-party Python package is neo4j-graphrag; the older neo4j-genai package name is deprecated. The package can orchestrate retrievers, embedders, knowledge-graph building and LLMs, but the course lab intentionally demonstrates the underlying data/query contracts directly. You may later plug in a local or paid model, but do not make the API/provider a prerequisite for understanding GraphRAG.

9. Wrong approaches and repairs

10. Cleanup / reset

Run only against the disposable Chapter 22 fixture.

CYPHER 25
DROP INDEX ch22_product_vector IF EXISTS;
DROP INDEX ch22_product_vector_none IF EXISTS;
DROP INDEX ch22_product_vector_binary IF EXISTS;
DROP INDEX ch22_chunk_vector IF EXISTS;
DROP INDEX ch22_catalog_ft IF EXISTS;
MATCH (n) WHERE n.labTag='ch22' DETACH DELETE n;
DROP CONSTRAINT ch22_product_id IF EXISTS;
DROP CONSTRAINT ch22_category_id IF EXISTS;
DROP CONSTRAINT ch22_store_id IF EXISTS;
DROP CONSTRAINT ch22_doc_id IF EXISTS;
DROP CONSTRAINT ch22_chunk_id IF EXISTS;

11. Final production judgment

Summary and next step

Chapter 22 has built a complete retrieval discipline: deterministic embeddings → exact baseline → HNSW ANN → observable index/options → Cypher SEARCH → rank-based hybrid retrieval → graph/business/security context → provenance-rich GraphRAG evidence → layered evaluation. Chapter 23 can now introduce Graph Data Science from the same principle: algorithms operate on explicit projections with measurable assumptions, not as magic graph intelligence.

Authoritative references

• Neo4j Operations Manual — current release — Current server line; the latest release at generation time is Neo4j 2026.07.1.
• Vector indexes — current Cypher Manual — Current CREATE/SHOW syntax, provider capabilities, filter properties, HNSW settings, quantization, population state, and query guidance.
• Cypher 25 SEARCH clause — Preferred Neo4j 2026.01+ vector search syntax, SCORE, in-index filters, post-filters, dimensions, and ANN limitations.
• Vector values and types — VECTOR semantics, coordinate type/dimension, LIST differences, and Enterprise/block-format storage boundary.
• Vector functions — vector.similarity.cosine/euclidean and VECTOR construction/inspection functions.
• Cypher additions/deprecations — SEARCH/vector additions, 2026.06 quantization-setting deprecation, and 2026.07 HFQ status.
• Operations deprecations — db.index.vector.queryNodes/queryRelationships deprecated in 2026.04 in favor of SEARCH.
• Built-in procedures — Legacy vector-query procedure signatures and replacement status; useful for version fallback history.
• Cypher and Neo4j edition differences — Community supports vector indexes over LIST embeddings but cannot persist VECTOR values as properties.
• Semantic-index authorization limitations — Fine-grained authorization can conservatively suppress full-text/vector semantic-index results.
• Hybrid search developer guide — Rank-source independence and weighted reciprocal-rank fusion patterns; do not compare raw heterogeneous scores.
• Hybrid search engineering article — 2026 engineering discussion of words + meaning + graph topology and rank-based fusion.
• Neo4j GraphRAG for Python — Official maintained GraphRAG package, server compatibility, and current package naming.
• GraphRAG RAG guide — Retriever/generation separation and SEARCH-based in-index filtering on Neo4j 2026.01+.
• GraphRAG Knowledge Graph Builder — Document/Chunk lexical graph, NEXT_CHUNK/FROM_DOCUMENT concepts, entity extraction, and provenance structure.
• Python Driver 6.3 — Optional application/evaluation harness; current official Python driver and Bolt compatibility.
• System requirements — Neo4j 2026.07.1 server supports Java 21/25 on documented platforms.