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 Retriever Vector Fulltext Graph When to use : : : : : : VectorRetriever ✓ — — Baseline; quick start HybridRetriever ✓ ✓ — Better recall; no graph context VectorCypherRetriever ✓ — ✓ GraphRAG without fulltext HybridCypherRetriever ✓ ✓ ✓ Production GraphRAG — default choice Text2CypherRetriever — — ✓ LLM generates Cypher; no embedder ToolsRetriever varies varies varies Multi retriever LLM routing 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+) 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 Providers All implement LLMBase . All support sync + async, tool calling, and automatic rate limiting. Class Extra Notes OpenAILLM openai Structured output; tool calling AzureOpenAILLM openai Azure hosted OpenAI AnthropicLLM anthropic Tool calling VertexAILLM google Structured output; tool calling MistralAILLM mistralai Tool calling CohereLLM cohere OllamaLLM ollama Local; tool calling BedrockLLM bedrock Boto3 Converse API; added v1.15.0 Embedder Providers All include automatic rate limiting with tenacity exponential backoff. Class Extra Dims OpenAIEmbeddings openai 3072 / 1536 AzureOpenAIEmbeddings openai varies VertexAIEmbeddings google 768 MistralAIEmbeddings mistralai 1024 CohereEmbeddings cohere 1024 OllamaEmbeddings ollama varies SentenceTransformerEmbeddings sentence transformers 384+ BedrockEmbeddings bedrock varies; added v1.15.0 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' 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: [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