Build GraphRAG retrieval pipelines on Neo4j using the neo4j-graphrag Python package (v1.16.0+). Covers retriever selection (VectorRetriever, HybridRetriever, VectorCypherRetriever, HybridCypherRetriever, Text2CypherRetriever, ToolsRetriever), external vector DB retrievers (Weaviate, Pinecone, Qdrant

Neo4j GraphRAG Skill When to Use Building GraphRAG retrieval pipelines with neo4j graphrag Python package Choosing between VectorRetriever, HybridRetriever, VectorCypherRetriever, HybridCypherRetriever Writing retrieval query Cypher fragments for graph augmented context Wiring retriever + LLM into a GraphRAG pipeline Using LLM routed multi retriever with ToolsRetriever Debugging low retrieval quality Integrating Neo4j with LangChain, LlamaIndex, or Haystack When NOT to Use KG construction from documents → neo4j document import skill Plain vector/semantic search without graph traversal → neo4j vector index skill Hybrid search that combines vector with fulltext or other ranked sources → neo4j vector index skill GDS algorithms (PageRank, Louvain, node embeddings) → neo4j gds skill Agent long term memory → neo4j agent memory skill Writing raw Cypher queries → neo4j cypher skill Retriever Selection Retriever Vector Fulltext Graph Best For : : : : : : VectorRetriever ✓ — — Baseline semantic search HybridRetriever ✓ ✓ — Better recall, no graph expansion VectorCypherRetriever ✓ — ✓ GraphRAG without fulltext HybridCypherRetriever ✓ ✓ ✓ Production GraphRAG — default Text2CypherRetriever — — ✓ NL→Cypher, no embedder ToolsRetriever varies varies varies LLM routed multi retriever WeaviateNeo4jRetriever ✓ — ✓ Vectors in Weaviate PineconeNeo4jRetriever ✓ — ✓ Vectors in Pinecone QdrantNeo4jRetriever ✓ — ✓ Vectors in Qdrant Install Requires: Python = 3.10, neo4j = 5.17.0 (driver 6.x supported). Step 2 — Choose Retriever Pick from [Retriever Selection]( retriever selection) table above. For custom Cypher hybrid search outside the neo4j graphrag retriever APIs, use neo4j vector index skill . Vector backend selection [v1.16+, auto] : on Neo4j 2026.01+ all four vector/hybrid retrievers auto route through the Cypher 25 SEARCH ... WHERE clause when filters are SEARCH compatible (simple AND comparisons) and all filter props are declared in the index WITH [n.prop] list. $or , $in , $like , or undeclared props → automatic fallback to db.index.vector.queryNodes() procedure path (with warning log). Declare filterable properties via filterable properties=[...] on create vector index() . Step 3 — Create Indexes (run once) If index not ONLINE: wait, poll every 5s. Do NOT start ingestion until ONLINE. Step 4 — Core Pattern (HybridCypherRetriever) VectorCypherRetriever Text2CypherRetriever Translates natural language to Cypher using an LLM. No embedder required. Security (v1.16.0+): Every LLM generated Cypher is run through EXPLAIN first. Any statement classified as write/destructive raises Text2CypherRetrievalError instead of executing — prevents prompt injection attacks. ToolsRetriever (LLM routed multi retriever) Filters (pre filter before vector search) query params (parameterized retrieval query) Cypher 25 SEARCH Clause (v1.16.0, Neo4j 2026.x+) Since v1.19, the vector and vector Cypher retrievers automatically prefix SEARCH queries with CYPHER 25 and fall back to the procedure based vector search when SEARCH is unsupported or fails. Component Imports (v1.19 — breaking, preparing 2.0) All components moved out of the experimental namespace. Old imports still work but emit a DeprecationWarning and will be removed in 2.0: neo4j graphrag.pipeline (v1.21+) = new lazy dataflow DSL ( Pipeline , LocalInterpreter , Sink ), unrelated to the experimental task graph Pipeline behind SimpleKGPipeline . neo4j graphrag.pipeline.kg builder does not exist → ModuleNotFoundError . Also since v1.19: Component / RunContext / TaskProgressNotifierProtocol live in neo4j graphrag.components.base , and malformed components raise ComponentDefinitionError (no longer PipelineDefinitionError ). Dataflow Pipeline DSL + Observers (v1.21) Lazy neo4j graphrag.pipeline.Pipeline + LocalInterpreter(observers=[...]) ; TextSplitter.iter chunks() . Full API → [references/pipeline dsl.md](references/pipeline dsl.md). ORDER BY on Cypher Retrievers (v1.16.0) If neo4j schema=None : retriever fetches schema automatically. For large schemas, pass a trimmed string to reduce LLM prompt size. Destructive query guard [v1.16+] : Text2CypherRetriever runs EXPLAIN on the generated Cypher before execution and rejects queries that produce writes ( CREATE , MERGE , DELETE , SET , REMOVE , etc.). LLM generated writes are never executed against the graph. Custom Prompt Template return context and response fallback Message History (multi turn) External Retrievers, LLM + Embedder Providers Weaviate / Pinecone / Qdrant constructors → [references/retrievers.md](references/retrievers.md external vector db retrievers) LLM classes ( OpenAILLM , AnthropicLLM , GeminiLLM , VertexAILLM , BedrockLLM , …), base url , token usage, close() ; embedder classes + dims → [references/providers.md](references/providers.md) Index Setup Schema Inspection Common Errors Error Cause Fix ModuleNotFoundError: neo4j genai Old package name pip uninstall neo4j genai && pip install neo4j graphrag retrieval query returns 0 rows Missing MATCH or wrong rel direction EXPLAIN the fragment; check CALL db.schema.visualization() KeyError: 'score' in results retrieval query RETURN missing score Add score to every retrieval query RETURN clause score variable not found score re declared in retrieval query Do not re declare score — it is auto injected Text2CypherRetrievalError LLM generated a write statement Expected security behavior (v1.16.0+); refine prompt or schema TypeError: coroutine Missing await / asyncio.run() Wrap async calls: asyncio.run(pipeline.run async(...)) Empty results from HybridRetriever Fulltext index not ONLINE SHOW INDEXES YIELD name, state WHERE state < 'ONLINE' VectorCypherRetriever + filters raises "requires: node label, embedding node property, …" (v1.19 name mismatch bug) fetch index infos sets self. embedding node property , constructor sets node embedding property Shim after construction: r. node embedding property = r. embedding node property or "embedding" ; append filter props to r. filterable properties Embedding dimension mismatch Index dims ≠ model dims Recreate index with correct dimensions= value Verification Checklist [ ] neo4j graphrag (not neo4j genai ) installed; neo4j = 5.17.0 driver [ ] Vector index ONLINE before ingesting embeddings or running retriever [ ] Fulltext index ONLINE if using Hybrid variants [ ] Embedding dims in create vector index match the embedder output [ ] retrieval query returns node and score in RETURN (not re declared) [ ] query params passed via retriever config on rag.search() (not on retriever constructor) [ ] API keys in env vars; never hardcoded [ ] llm.close() called when done to release resources References Load on demand: [references/retrievers.md](references/retrievers.md) — per retriever constructor params, external vector DB retrievers, result formatter , pre filter operators [references/providers.md](references/providers.md) — LLM + embedder provider classes, extras, defaults [references/pipeline dsl.md](references/pipeline dsl.md) — dataflow Pipeline DSL, Source / Sink , stage observers [v1.21] [references/kg builder.md](references/kg builder.md) — SimpleKGPipeline constructor, schema, splitters [references/knowledge graph construction.md](references/knowledge graph construction.md) — advanced KG pipeline customization [neo4j graphrag package docs](https://neo4j.com/docs/neo4j graphrag python/current/) [RAG & GraphRAG user guide](https://neo4j.com/docs/neo4j graphrag python/current/user guide rag.html) [KG Builder user guide](https://neo4j.com/docs/neo4j graphrag python/current/user guide kg builder.html) [GitHub — neo4j graphrag python](https://github.com/neo4j/neo4j graphrag python) [Examples folder](https://github.com/neo4j/neo4j graphrag python/tree/main/examples)

neo4j-graphrag-skill