iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
To combine Neo4j graph search with vector search for RAG, run three retrieval signals against one graph: a vector index for meaning, a full-text index for exact terms, and a Cypher traversal that expands the best hits into connected entities and facts. In Neo4j’s official GraphRAG Python package (neo4j-graphrag), the two retrievers built for this pattern are HybridRetriever, which combines vector and full-text results, and HybridCypherRetriever, which adds a Cypher retrieval query after the hybrid search. This guide explains when to use each, the build order, and the version details to confirm before you copy any example.
Why one search signal is not enough
In this architecture the graph acts as memory: entities and relationships persist and can be traversed when a question needs more than a single passage. Each retrieval signal fails on a different kind of question, which is why a single index rarely covers a production workload.
- Vector similarity finds text or nodes whose meaning matches the query even when the wording differs. A question about “retrying failed jobs with increasing delays” can surface a passage that says “exponential backoff.”
- Full-text search matches literal strings: product names, API names, acronyms, error codes, and identifiers where a near miss is simply wrong. A query for one specific error code should not return a semantically similar but different code.
- Graph traversal expands promising starting nodes into connected entities and facts. A question such as “which contracts are affected if supplier X changes its data-retention terms?” needs hops from a supplier to contracts to clauses, which a flat list of passages cannot supply.
These examples are illustrative, not measured results. Neo4j’s July 8, 2026 developer article describes the same combination as lexical, semantic, and structural signals, followed by expansion from starting points into connected context for GraphRAG (Neo4j Developer Blog).
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Choose the retriever before you build the indexes
The package’s RAG user guide and its API documentation describe separate retrievers for each combination of signals. Picking the right one first tells you which indexes you need.
#1 Best Overall
| Retriever | Search stage | Graph traversal after search | Best fit |
|---|---|---|---|
VectorCypherRetriever |
Vector index only | Yes, a Cypher query runs on vector hits | Paraphrased questions that need connected facts, where exact-term recall is unnecessary |
HybridRetriever |
Vector index plus full-text index | No | Mixed questions with paraphrases and exact names, where flat passages are enough |
HybridCypherRetriever |
Vector index plus full-text index | Yes, a Cypher query runs on hybrid hits | Mixed questions that also need relationship context around the matches |
Answer three questions about your workload to choose:
- Do users paraphrase, and also type exact names or identifiers? If yes, you need the full-text index, so use a hybrid retriever.
- Do correct answers depend on relationships between entities, such as multi-hop links? If yes, you need a Cypher retrieval query.
- If the answer to both is yes, use
HybridCypherRetriever. If the answer to only the first is yes, useHybridRetriever. If only the second is yes, useVectorCypherRetriever.
The build sequence
- Model the graph around the relationships your answers need. Decide which entities and edges let a retrieved chunk answer multi-hop questions, for example Chunk to Document to Product, or Component to Supplier to Contract. The vector index finds a starting node, but traversal adds value only when those edges exist. If your graph stores chunks with no meaningful edges,
HybridCypherRetrieveradds little overHybridRetriever. - Create embeddings and a vector index. Embed the indexed text and every incoming query with the same embedding model, and set the index dimension to that model’s output size. The package overview states that the index dimension must match the embedding dimension (GraphRAG for Python documentation). For a model that outputs 1536 dimensions with cosine similarity, the index looks like this. Label and property names are examples.
CREATE VECTOR INDEX chunk_embedding IF NOT EXISTS FOR (c:Chunk) ON (c.embedding) OPTIONS { indexConfig: { `vector.dimensions`: 1536, `vector.similarity_function`: 'cosine' } } - Create a full-text index for exact terms. The hybrid retrievers need the full-text index to exist before retrieval runs, and you pass its name to the retriever. The example below covers the chunk text property.
CREATE FULLTEXT INDEX chunk_text IF NOT EXISTS FOR (c:Chunk) ON EACH [c.text]The statements above use standard Cypher syntax for Neo4j 5. Confirm the exact clauses against the Cypher manual for your server version before you run them.
- Configure the retriever. Point the retriever at both indexes by name, then add the Cypher retrieval query if you chose
HybridCypherRetrieverorVectorCypherRetriever. Check the parameter names in the API documentation for your installed package version, because the parameter names are part of the moving reference. - Shape the returned context. The retrieval query starts from each matched node and runs your traversal. Return specific properties and related entity values, not whole nodes. Neo4j recommends returning node properties instead of nodes in the documented vector-plus-Cypher pattern (RAG user guide). Limit hop depth and row counts, because each extra hop adds candidate facts the model must sort through, which can dilute the answer.
Ranking the combined results
When the signals return separate ranked lists, something has to merge them. In its July 2026 example, Neo4j re-ranks the combined results with weighted reciprocal rank fusion (WRRF). Treat the weights as a starting point rather than a default. Neo4j’s documentation does not give universal weights, and the right balance depends on how your questions mix paraphrase, exact terms, and relationships. Neo4j’s developer post on hybrid retrieval with the package covers the package-side implementation (Neo4j Developer Blog).
David Pond, Neo4j Principal Database Product Manager, describes the approach in the July 8, 2026 post this way: “Hybrid search in Neo4j can combine words, meaning, relationships, and structure in one retrieval pipeline.” That is the vendor’s own description of the design, not independent evidence that it improves results. The same post presents structural graph similarity as an additional option alongside lexical and semantic matching.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallEvaluate retrieval before you judge the answers
Test retrieval separately from generation. If the right evidence never reaches the prompt, a better model will not fix the answer. Build a small, hand-reviewed question set covering three types:
- Paraphrase questions: the same meaning as a source passage, with different wording.
- Exact-term questions: product names, identifiers, error codes, and API names.
- Relationship questions: answers that require two or more hops through the graph.
For each question, record which nodes and evidence came back, and at what rank, before you read the generated answer. Measure whether the right evidence appears, where it ranks in the combined list, and how long retrieval takes. Neo4j’s documentation describes these methods but does not provide a benchmark that establishes a universal recall or ranking configuration, so the numbers that count are the ones from your own corpus.
Versions and limits to confirm before you copy examples
The package documentation is a moving “current” reference. The details below were checked in early October 2026. Confirm them against your deployed server and installed package.
- Minimum server versions: the package docs list Neo4j support from 5.18.1 and Neo4j Aura from 5.18.0 (GraphRAG for Python documentation).
- In-index filtering: the docs state that Neo4j 2026.01 or later enables the
SEARCHclause with in-index filtering for filterable vector properties. Confirm this boundary if your design depends on filtered vector search. - Approximate results: vector indexes use approximate nearest-neighbor search, so the returned neighbors may not be the exact top matches (RAG user guide).
- Optional
nlpextra: the package’s spaCy-based extra is not supported on Python 3.14 because of an upstream issue. This matters only if you use that optional feature. - Older tutorials: vendor tutorials are useful for concepts, but check their code against the current package API before running it.
Where the vectors live
The package lists external retrievers for Weaviate, Pinecone, and Qdrant, so the graph does not force every vector into Neo4j. Keeping vectors in Neo4j gives you one store for the graph, the indexes, and the traversal. An external vector database adds a second system and its client code, and the identifiers it returns must map back to Neo4j nodes before traversal can start. Choose based on the infrastructure you already run. The sources do not establish a performance advantage for either placement.
When results look wrong
- An exact identifier is missing. Confirm the full-text index exists, that the name you pass matches it, and that it covers the property where the identifier is stored.
- A paraphrase is missing. Revisit step 2 of the build sequence and confirm the embedded field contains the wording you expect, and that the query and indexed embeddings come from the same model.
- Graph context is empty. Check that the edges exist with the labels and relationship types your traversal names. A Cypher pattern that does not match returns no context.
- Index creation or queries fail after an upgrade. Check the server and package versions against the boundaries listed above before changing the code.
Going further
Neo4j publishes Essential GraphRAG as an official PDF guide, which is an optional companion for the concepts covered here (Essential GraphRAG guide).
Quick Recap
Best Value
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
