LlamaIndex Neo4j Graph Stores Integration

0.7.0 · active · verified Thu Apr 16

The `llama-index-graph-stores-neo4j` library provides an integration for LlamaIndex to use Neo4j as a backend for graph stores. It enables persisting, visualizing, and querying knowledge graphs directly within a Neo4j database, supporting both triplet-based and property graph models. The library is actively maintained as part of the broader LlamaIndex ecosystem, with frequent updates to ensure compatibility and introduce new features.

Common errors

```
ModuleNotFoundError: No module named 'llama_index.graph_stores.neo4j'
```
cause The `llama-index-graph-stores-neo4j` package is not installed or there's a typo in the import statement.

fix Run `pip install llama-index-graph-stores-neo4j`. Verify the exact import path, which is `from llama_index.graph_stores.neo4j import ...`.
```
neo4j.exceptions.ServiceUnavailable: Could not perform discovery. No routing servers available.
```
cause The Neo4j database is not running, is inaccessible from the client, or the connection URI/credentials are incorrect.

fix Ensure the Neo4j database is started and reachable (e.g., check Docker container status, network connectivity). Verify `NEO4J_URI`, `NEO4J_USERNAME`, and `NEO4J_PASSWORD` environment variables or constructor arguments are correct.
```
ValueError: OPENAI_API_KEY environment variable not set.
```
cause LlamaIndex components (like graph extractors) often default to using OpenAI models, which require an API key, even if you're only interacting with the graph store.

fix Set the `OPENAI_API_KEY` environment variable. For example: `export OPENAI_API_KEY='sk-...'`. Alternatively, configure LlamaIndex `Settings` to use a different LLM.

Warnings

breaking The LlamaIndex Neo4j integration evolved from triplet-based (`Neo4jGraphStore`) to a property graph model (`Neo4jPropertyGraphStore`). Existing codebases using the older triplet model for graph creation or specific data representation might need significant refactoring.
Fix: Migrate to `Neo4jPropertyGraphStore` for richer graph representation with nodes and properties. Review LlamaIndex documentation for property graph index construction.
gotcha Initializing `Neo4jPropertyGraphStore` with large existing graphs can be very slow due to the `refresh_schema()` operation, which fetches the entire schema from Neo4j.
Fix: Set `refresh_schema_on_startup=False` during initialization if the schema is stable or refresh manually. Example: `Neo4jPropertyGraphStore(..., refresh_schema_on_startup=False)`.
gotcha `CypherSyntaxError` or connection issues when interacting with Neo4j, especially for advanced queries or specific APOC procedures.
Fix: Ensure your Neo4j database is running version 5.11.0 or greater, as certain Cypher features and vector indexing require it. Verify that APOC procedures are correctly installed and enabled in your Neo4j configuration. Double-check Neo4j URI, username, and password.

Install

pip install llama-index-graph-stores-neo4j Install package

Imports

Neo4jGraphStore

from llama_index.graph_stores.neo4j import Neo4jGraphStore

Neo4jPropertyGraphStore

from llama_index.graph_stores.neo4j import Neo4jPropertyGraphStore

Quickstart

This quickstart demonstrates how to initialize the `Neo4jPropertyGraphStore` and integrate it with LlamaIndex to create a knowledge graph. It assumes a running Neo4j instance and requires an OpenAI API key for LlamaIndex's internal LLM processing during graph extraction. It uses environment variables for Neo4j credentials and the OpenAI API key for secure configuration.

import os
from llama_index.graph_stores.neo4j import Neo4jPropertyGraphStore
from llama_index.core import StorageContext, KnowledgeGraphIndex, SimpleDirectoryReader
from llama_index.core.schema import Document

# Ensure Neo4j is running (e.g., via Docker) and credentials are set
# For local Docker setup: docker run -p 7474:7474 -p 7687:7687 -e NEO4J_AUTH=neo4j/password --name neo4j-apoc neo4j:latest

NEO4J_URI = os.environ.get("NEO4J_URI", "bolt://localhost:7687")
NEO4J_USERNAME = os.environ.get("NEO4J_USERNAME", "neo4j")
NEO4J_PASSWORD = os.environ.get("NEO4J_PASSWORD", "password") # Default password for fresh install
NEO4J_DATABASE = os.environ.get("NEO4J_DATABASE", "neo4j")
OPENAI_API_KEY = os.environ.get("OPENAI_API_KEY", "") # Required for LlamaIndex processing

if not OPENAI_API_KEY:
    raise ValueError("OPENAI_API_KEY environment variable not set.")

# Initialize Neo4j Property Graph Store
graph_store = Neo4jPropertyGraphStore(
    username=NEO4J_USERNAME,
    password=NEO4J_PASSWORD,
    url=NEO4J_URI,
    database=NEO4J_DATABASE,
)

# Create storage context
storage_context = StorageContext.from_defaults(graph_store=graph_store)

# Example document (in a real scenario, use SimpleDirectoryReader or other loaders)
documents = [
    Document(text="LlamaIndex is a data framework for LLM applications. It helps connect custom data sources to LLMs.")
]

# Create a Knowledge Graph Index
# Note: This will extract entities and relationships and store them in Neo4j.
index = KnowledgeGraphIndex.from_documents(
    documents,
    storage_context=storage_context,
    # Other parameters like `llm`, `kg_extractors` can be configured
    # For this quickstart, default LLM settings will use OpenAI, hence API key is needed.
    max_triplets_per_chunk=2, # For simpler quickstart
)

print("Knowledge Graph Index created and stored in Neo4j.")

# Example query (requires an LLM configured in LlamaIndex Settings or passed to the query engine)
# query_engine = index.as_query_engine()
# response = query_engine.query("What is LlamaIndex?")
# print(response)

view raw JSON →