To combine Neo4j graph search with vector search in a retrieval-augmented generation (RAG) system, use a hybrid retriever from Neo4j’s official neo4j-graphrag-python package with a Cypher retrieval query. A vector index and a full-text index find starting nodes, and a Cypher query then walks the graph from those nodes to pull connected facts into the prompt. The package names this pattern HybridCypherRetriever, and it is the right starting point when a question needs both exact wording and relationship context.
The sections below cover what each retrieval signal contributes, how to choose a retriever, the build order, how to evaluate retrieval before generation, and the version boundaries to check before copying any example.
As an Amazon Associate I earn from qualifying purchases.
What each retrieval signal contributes
Neo4j’s developer team describes the goal as a single pipeline that can “combine words, meaning, relationships, and structure in one retrieval pipeline” (David Pond, Neo4j Developer Blog, July 8, 2026, Hybrid Search in Neo4j: Full-Text, Vectors, and Graph Topology with Cypher). That is a vendor description of the approach, not independent proof of results. The practical question is what each signal catches and where it fails.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →| Signal | Best at | Weak spot | Neo4j component |
|---|---|---|---|
| Vector similarity | Paraphrases and concepts worded differently from the source text | Less reliable when the exact string matters; results are approximate | A vector index over embeddings stored on nodes |
| Full-text search | Literal names, acronyms, error codes, product and API names, domain terms | Misses questions that describe a concept without using the term | A full-text index whose name is passed to the retriever |
| Graph traversal | Multi-hop questions and connected entities or facts | Adds nothing if the graph lacks the relevant edges | A Cypher retrieval query that starts from the retrieved nodes |
Neo4j’s July 2026 article also presents weighted reciprocal rank fusion (WRRF) as a way to re-rank the combined lexical and semantic results before graph expansion. Treat it as one implementation option, covered in the evaluation section below.
#1 Best Overall
Choosing a retriever
The package’s RAG user guide and its API documentation describe separate retrievers for vector search, vector search followed by Cypher traversal, hybrid vector plus full-text search, and hybrid search followed by Cypher traversal. Their differences come down to two questions: does the query need lexical matching, and does the answer need connected context?
| Retriever | Vector search | Full-text search | Cypher graph traversal | Use it when |
|---|---|---|---|---|
HybridRetriever |
Yes | Yes | No | Both semantic and literal matching matter, and isolated matching passages answer the question |
HybridCypherRetriever |
Yes | Yes | Yes | Both matching styles matter and the answer depends on connected entities or facts |
VectorCypherRetriever |
Yes | No | Yes | Semantic matching plus graph context is enough and lexical recall is not needed |
The package also offers a vector-only retriever without traversal, which is the simplest option when no question needs relationship context.
Vectors do not have to live inside Neo4j. The package lists external retrievers for Weaviate, Pinecone, and Qdrant, so graph storage in Neo4j does not force every embedding into the same database. The trade-off is extra client code and provider-specific identifier mapping between the vector store and the graph nodes.
Building the pipeline
Build in this order. Each step depends on the one before it, so verify the indexes before writing the traversal query.
1. Model the graph around answerable relationships
Decide which entities and edges let a retrieved chunk answer a multi-hop question. In a support knowledge base, for example, a troubleshooting article might link to the product version it applies to, the component it affects, and the error codes it mentions. A vector index can identify a relevant starting node, but traversal only helps when the graph holds the connection the question needs.
2. Create embeddings and a vector index
Use the same embedding model for the indexed content and for queries. The package overview states that the vector index dimension must match the embedding dimension (GraphRAG for Python documentation). Check the dimension right after creating the index, because a mismatch is a setup error that surfaces early if you look for it.
3. Create a full-text index for exact terms
The hybrid retrievers require both a vector index and a full-text index. The full-text index must already exist, and its name is supplied to the retriever (RAG user guide; API documentation). Index the text properties that carry literal names, identifiers, and acronyms, because that is where lexical matching adds recall.
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 →4. Choose the retriever and pass the index names
Pick the retriever from the table above. For a graph-backed answer with both matching styles, use HybridCypherRetriever and pass both index names. If lexical recall turns out to be unnecessary on your corpus, switch to VectorCypherRetriever and remove the full-text dependency.
Best Value
5. Write the retrieval Cypher query and shape the context
The Cypher retrieval query starts from the nodes the indexes return and fetches the context around them. Return properties and related entity names rather than whole node objects. Neo4j’s documentation recommends returning node properties in the documented vector-plus-Cypher pattern (RAG user guide). Include only the fields the answer model needs, because every extra property lengthens the prompt and dilutes the evidence.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Evaluate retrieval before generation
Test retrieval on its own, then add the language model. Build a question set with three groups:
- Paraphrases of passages in the corpus, where the vector index should succeed.
- Exact names, identifiers, and error codes, where the full-text index should contribute.
- Relationship questions whose answer spans two or more connected nodes, where traversal should contribute.
For each question, inspect the retrieved nodes and the evidence passed to the model before judging the generated answer. Run the same questions against a single-signal variant of the pipeline so you can see whether the added signal changes the evidence.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Clear out junk files and repair common Windows errors3Scan for outdated or missing drivers - takes under a minuteSeveral points need care:
- Approximate results. Vector indexes use approximate nearest-neighbor search, so returned results may not be the exact nearest neighbors (RAG user guide). Measure recall on your own questions rather than assuming it.
- Ranking weights. The weighted reciprocal rank fusion in Neo4j’s 2026 article is one configuration. Its weights are not a universal default; tune them against your own question set (Neo4j Developer Blog, July 8, 2026).
- Structural similarity. The same article presents structural graph similarity as an additional option. Test it as a candidate signal; published results do not establish that it improves results for every application.
- Performance. Neo4j’s documentation does not publish a general accuracy or latency benchmark for these retrievers. Measure both on your corpus and hardware.
Version and deployment checks
The package documentation is a moving reference, so confirm each item against the versions you actually deploy before copying examples.
Quick Recap
- Server support. The current package documentation lists Neo4j support from 5.18.1 and Aura support from 5.18.0 (GraphRAG for Python documentation).
- In-index filtering. The same documentation says Neo4j 2026.01 and later enable the
SEARCHclause with in-index filtering for filterable vector properties. Older servers need a different filtering approach. - Python and the optional
nlpextra. The extra that uses spaCy is not supported on Python 3.14 because of an upstream issue. This matters only if you install that extra. - API names. Check retriever class names and constructor arguments against the installed package version, not against older tutorials.
When the graph is not worth the added complexity
- Single-passage answers. If each question is answered by one chunk, the vector-only retriever or
HybridRetrievercovers it. Graph expansion adds prompt length and query work without adding evidence. - Sparse relationships. If the graph contains few real edges, traversal returns little beyond the seed nodes. Fix the data model first.
- Identifier-dominated queries. If almost every query is an exact identifier, full-text search may be the simpler system to evaluate first, and vector search can be added only where paraphrase failures appear.
“
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.
