Retrieval

When you ask GraphRAG a question, it doesn’t just search for keywords. It uses multiple retrieval paths in parallel — like asking five different experts to find relevant information, then combining their best findings into one answer. This document explains how each path works, what it contributes, and how they perform individually and together.

The Big Picture

                          Your Question
                               |
                    ┌──────────┴──────────┐
                    v                      v
            1. Extract Keywords      2. Embed Question
                    |                      |
         ┌─────────┴──────────────────────┴─────────┐
         v                   v                       v
   3a. RELATES Vector   3b. Text-to-Cypher    4. Entity Discovery
   (fact search)        (graph queries)       (name matching)
         |                   |                       |
         └───────────────────┴───────────────────────┘
                             |
                    5. Relationship Expansion
                             |
                    6. Chunk Retrieval (4 paths)
                    ┌────┬────┬────┬────┐
                    v    v    v    v    |
                 Full- Vector MENT- 2-hop
                 text  search IONED graph
                    └────┴────┴────┴────┘
                             |
                    7. Document Mapping
                             |
              ┌──────────────┴──────────────┐
              v                              v
   8a. Rerank Passages              8b. Filter Facts
   (stored embeddings)              (score threshold)
              |                              |
              └──────────────┬──────────────┘
                             v
                    9. Assemble Context ← Cypher results
                             |               (direct, no reranking)
                             v
                    Final LLM Answer

Step-by-Step Explanation

Step 1 — Keyword Extraction

What it does: Pulls out the important words from your question. How: Two methods run together:

Simple filter: Removes common words (“the”, “is”, “what”) and keeps meaningful terms
LLM extraction: Asks the language model to identify proper nouns, names, places, and specific terms

Example:

Question: “What did Professor Harmon discover at the lighthouse?” Simple keywords: ["professor", "harmon", "discover", "lighthouse"] LLM keywords: ["Professor Harmon", "lighthouse"]

Code: MultiPathRetrieval._extract_keywords() in multi_path.py

Step 2 — Embed the Question

What it does: Converts the question text into a numerical vector (a list of numbers) that captures its meaning. Why: This vector is used later to find chunks and facts that are semantically similar to the question — even if they don’t share the exact same words. Code: Embedder.aembed_query() in providers/base.py

Step 3a — RELATES Vector Search (Knowledge Graph Facts)

What it does: Searches the relationship edges in the graph by meaning similarity. Every relationship between entities (like “Alice WORKS_AT Acme Corp”) has been embedded as a vector during ingestion. This step finds the relationships most relevant to the question. Returns: Fact strings like:

Alice —[WORKS_AT]→ Acme Corp: Alice is a senior engineer at Acme Corp

Important: Facts are scored by their vector similarity to the question. Low-scoring facts are filtered out (see Step 8b) to reduce noise. Code: search_relates_edges() in entity_discovery.py

Step 3b — Text-to-Cypher (Graph Queries)

What it does: Asks the LLM to write a database query (in the Cypher language) that can directly answer the question from the graph structure. Why it matters: Some questions need structural information that text search can’t provide:

“How many organizations are in the story?” → needs COUNT
“What connects Alice and the castle?” → needs graph path traversal
“List all locations mentioned” → needs MATCH (l:Location) RETURN l.name

How it works:

The LLM receives a description of the graph schema (what node types exist, how edges work)
It generates a Cypher query tailored to the question
The query is validated (read-only, valid labels) and sanitized (adds LIMIT, removes unsupported FalkorDB patterns)
If the query executes successfully, the results go directly to the final LLM context — they are NOT filtered by the reranker

Runs in parallel with step 3a to avoid adding latency. If it fails, the other paths still produce results. Code: execute_cypher_retrieval() in cypher_generation.py

Step 4 — Entity Discovery

What it does: Finds entities (people, places, organizations, etc.) in the graph that match the question’s keywords. Two paths:

Path A — Name matching: Searches entity names using CONTAINS (e.g., “lighthouse” matches “The Old Lighthouse”). Runs as a single batched database query for efficiency.
Path B — Fulltext search: Uses the text search index on entity names and descriptions. Good for partial matches and stemming.

Entities found in steps 3a and 3b are also merged in here. Code: discover_entities() in entity_discovery.py

Step 5 — Relationship Expansion

What it does: Starting from the discovered entities, traverses the graph to find their relationships. Two depths:

1-hop: Direct relationships (Alice → WORKS_AT → Acme Corp)
2-hop: Indirect connections through an intermediate entity (Alice → WORKS_AT → Acme → LOCATED_IN → New York)

Returns: Formatted relationship strings with evidence, like:

Alice —[WORKS_AT]→ Acme Corp: Alice joined Acme as a senior engineer in 2019
Acme Corp —[LOCATED_IN]→ New York: Acme Corp headquarters is in Manhattan

Code: expand_relationships() in relationship_expansion.py

Step 6 — Chunk Retrieval (4 Paths)

What it does: Finds the actual text passages (chunks) from the original documents that are most relevant to the question. This is the core of passage-based retrieval. Four independent paths ensure we don’t miss relevant passages:

Path	Method	What it finds
A — Fulltext	Keyword search on chunk text	Passages containing exact keyword matches
B — Vector	Embedding similarity search	Passages with similar meaning (even without shared keywords)
C — MENTIONED_IN	Graph traversal from entities to their source chunks	Passages where discovered entities were originally extracted
D — 2-hop	Entity → related entity → chunk	Passages containing entities that are connected to the question’s entities

All four paths contribute to a single pool of candidate chunks. Code: retrieve_chunks() in chunk_retrieval.py

Step 7 — Document Mapping

What it does: Looks up which source document each chunk came from, so the final answer can reference the source. Code: fetch_chunk_documents() in chunk_retrieval.py

Step 8 — Reranking (Differentiated)

Facts and passages are ranked by different criteria because they have different characteristics:

8a — Passage Reranking (Stored Embeddings)

What it does: Ranks the candidate chunks by how similar their meaning is to the question, keeping only the top 15. How: Each chunk already has an embedding vector stored in the graph from ingestion. Instead of re-computing embeddings (which would require an expensive API call), we fetch the stored vectors and compute cosine similarity locally. This makes reranking instant instead of taking 2-3 seconds. Code: rerank_chunks() in result_assembly.py

8b — Fact Filtering (Score Threshold)

What it does: Filters knowledge graph facts by their vector similarity score from step 3a. Why separate? Facts are short structured strings (“Alice —[WORKS_AT]→ Acme”) while passages are long prose paragraphs. Short text has higher cosine similarity variance — a threshold that works for passages would let too many irrelevant facts through. Facts use a higher threshold (0.25) and always keep at least 3 top facts. Code: filter_facts_by_relevance() in result_assembly.py

Step 9 — Context Assembly

What it does: Combines everything into a structured context document that the LLM uses to generate the final answer. Sections (in order):

Answer format hint — e.g., “This is a yes/no question” for yes/no questions
Graph Query Results — Direct results from text-to-cypher (bypasses reranking)
Key Entities — Names and descriptions of relevant entities
Entity Relationships — How entities connect to each other
Knowledge Graph Facts — Evidence from relationship embeddings
Source Document Passages — Ranked text passages with source attribution

The final LLM receives this structured context and generates a natural language answer. Code: assemble_raw_result() in result_assembly.py

Benchmark Results

All experiments were run on the same pre-built graph (graphrag_sdk_v2_retrieval_benchmark) with 100 questions scored by an LLM judge (0-10 scale).

Enhancement Comparison

Configuration	Accuracy	vs Baseline	P50 Latency	What changed
Baseline (MultiPath only)	83.8%	—	4.2s	Current default
+ Text-to-Cypher	84.2%	+0.4%	5.7s	Added graph query path
+ All Enhancements	84.8%	+1.0%	5.7s	Stored rerank + fact filtering + cypher

Accuracy by Question Type

Question Type	Baseline	All Enhancements	Change
Complex Reasoning	83%	84%	+1%
Contextual Summarize	84%	87%	+3%
Creative Generation	80%	80%	—
Fact Retrieval	85%	85%	—

Text-to-Cypher helps most with Contextual Summarize questions where structured graph relationships provide the context the LLM needs to produce comprehensive summaries.

Isolated Path Performance

Each retrieval path was tested in isolation (only that path, no others) to measure its individual contribution:

Rank	Retrieval Path	Accuracy Alone	Role in Pipeline
1	Vector Search (chunk embeddings)	77.4%	The backbone — strongest single path
2	Fulltext Search (keyword matching)	74.8%	Catches exact keyword matches that vectors miss
3	RELATES Vector (relationship facts)	70.0%	Provides structured knowledge (who/what/where)
4	Graph Traversal (MENTIONED_IN edges)	69.1%	Links entities back to their source text
5	Text-to-Cypher (LLM-generated queries)	53.0%	Weakest alone, but adds unique structural signal

Key insight: No single path matches the combined pipeline (83.8%). The value is in multi-path fusion — each path finds information the others miss, and together they cover more ground than any individual approach.

Latency Profile

Retrieval Path	P50 Latency	Notes
RELATES vector search	1.6s	Fastest — single vector index query
Vector chunk search	2.2s	Fast — single vector index query
Fulltext chunk search	2.7s	Multiple keyword queries
Graph traversal	2.8s	Depends on entity fanout
Text-to-Cypher	4.5s	Includes LLM call for query generation
Full MultiPath pipeline	4.2s	Steps run in parallel where possible

Configuration

Toggling Text-to-Cypher

from graphrag_sdk.retrieval.strategies.multi_path import MultiPathRetrieval

# Without text-to-cypher (default)
strategy = MultiPathRetrieval(
    graph_store=rag.graph_store,
    vector_store=rag.vector_store,
    embedder=embedder,
    llm=llm,
    enable_cypher=False,  # default
)

# With text-to-cypher (opt-in, adds ~1.5s latency)
strategy = MultiPathRetrieval(
    graph_store=rag.graph_store,
    vector_store=rag.vector_store,
    embedder=embedder,
    llm=llm,
    enable_cypher=True,
)

result = await rag.completion("Your question", strategy=strategy)

Tuning Parameters

Parameter	Default	What it controls
`chunk_top_k`	15	Maximum passages after reranking
`max_entities`	30	Maximum entities to keep from discovery
`max_relationships`	20	Maximum relationships to include
`rel_top_k`	15	RELATES edge vector search results
`enable_cypher`	False	Toggle text-to-cypher path (opt-in)

Using the External Reranker

The pipeline has built-in reranking (step 8), but you can also apply an external reranker after retrieval:

from graphrag_sdk.retrieval.reranking_strategies.cosine import CosineReranker

reranker = CosineReranker(embedder=embedder, top_k=10)
result = await rag.completion("Your question", reranker=reranker)

File Reference

File	What it contains
`multi_path.py`	Main orchestrator — coordinates all 9 steps
`entity_discovery.py`	RELATES vector search + 2-path entity discovery
`chunk_retrieval.py`	4-path chunk retrieval + document mapping
`relationship_expansion.py`	1-hop and 2-hop relationship traversal
`result_assembly.py`	Reranking, fact filtering, question hints, context assembly
`cypher_generation.py`	Text-to-Cypher: schema prompt, generation, validation, execution
`base.py`	RetrievalStrategy abstract base class
`local.py`	Simple vector + 1-hop retrieval (alternative strategy)
`cosine.py`	External cosine reranker
`router.py`	Semantic router for conditional strategy selection

Home

Pipeline

Ontology

Reference

The Big Picture

Step-by-Step Explanation

Step 1 — Keyword Extraction

Step 2 — Embed the Question

Step 3a — RELATES Vector Search (Knowledge Graph Facts)

Step 3b — Text-to-Cypher (Graph Queries)

Step 4 — Entity Discovery

Step 5 — Relationship Expansion

Step 6 — Chunk Retrieval (4 Paths)

Step 7 — Document Mapping

Step 8 — Reranking (Differentiated)

8a — Passage Reranking (Stored Embeddings)

8b — Fact Filtering (Score Threshold)

Step 9 — Context Assembly

Benchmark Results

Enhancement Comparison

Accuracy by Question Type

Isolated Path Performance

Latency Profile

Configuration

Toggling Text-to-Cypher

Tuning Parameters

Using the External Reranker

File Reference

​The Big Picture

​Step-by-Step Explanation

​Step 1 — Keyword Extraction

​Step 2 — Embed the Question

​Step 3a — RELATES Vector Search (Knowledge Graph Facts)

​Step 3b — Text-to-Cypher (Graph Queries)

​Step 4 — Entity Discovery

​Step 5 — Relationship Expansion

​Step 6 — Chunk Retrieval (4 Paths)

​Step 7 — Document Mapping

​Step 8 — Reranking (Differentiated)

​8a — Passage Reranking (Stored Embeddings)

​8b — Fact Filtering (Score Threshold)

​Step 9 — Context Assembly

​Benchmark Results

​Enhancement Comparison

​Accuracy by Question Type

​Isolated Path Performance

​Latency Profile

​Configuration

​Toggling Text-to-Cypher

​Tuning Parameters

​Using the External Reranker

​File Reference

The Big Picture

Step-by-Step Explanation

Step 1 — Keyword Extraction

Step 2 — Embed the Question

Step 3a — RELATES Vector Search (Knowledge Graph Facts)

Step 3b — Text-to-Cypher (Graph Queries)

Step 4 — Entity Discovery

Step 5 — Relationship Expansion

Step 6 — Chunk Retrieval (4 Paths)

Step 7 — Document Mapping

Step 8 — Reranking (Differentiated)

8a — Passage Reranking (Stored Embeddings)

8b — Fact Filtering (Score Threshold)

Step 9 — Context Assembly

Benchmark Results

Enhancement Comparison

Accuracy by Question Type

Isolated Path Performance

Latency Profile

Configuration

Toggling Text-to-Cypher

Tuning Parameters

Using the External Reranker

File Reference