Load Graph Database Data with Cypher Queries
Load documents from Cypher query results against Neo4j, AWS Neptune, or Memgraph.
Why it matters
Ingest structured data from graph databases like Neo4j, AWS Neptune, and Memgraph into your AI applications. This asset executes custom Cypher queries to extract and format data, making it readily available for LLM-based analysis and knowledge graph construction.
Outcomes
What it gets done
Connect to various graph database endpoints (Neo4j, Neptune, Memgraph) using provided credentials.
Execute user-defined Cypher queries with optional parameters to retrieve specific data.
Transform query results into a YAML string representation for document ingestion.
Integrate seamlessly with LlamaIndex for data loading or as a tool within LangChain agents.
Install
Add it to your toolbox
Run in your project directory:
curl -fsSL https://spark.entire.vc/get/li-reader-readers-graphdb-cypher | bash Overview
Graph Database Cypher Loader
A LlamaIndex reader that runs a Cypher query against Neo4j, AWS Neptune, or Memgraph and returns the results as YAML-rendered documents. Use when you already store data in a Cypher-compatible graph database and want a query-defined subset loaded for retrieval.
What it does
The Graph Database Cypher Loader populates LlamaIndex documents from the results of Cypher queries run against a graph database endpoint. The user specifies a GraphDB endpoint URL with optional credentials to initialize the reader, declares the Cypher query and any optional parameters, and the loader fetches the nested result documents. Results are turned into a YAML representation and then into a string for the document text, so nested or structured query results stay readable rather than being flattened into an opaque blob.
GraphDBCypherReader is initialized with a URI, username, password, and database name, and load_data takes the Cypher query string along with a parameters dictionary for parameterized queries (for example, filtering by a tag value). The source's own example queries a public Neo4j demo instance (demo.neo4jlabs.com, database stackoverflow) for the ten most recent Stack Overflow questions tagged with a given topic, using MATCH/RETURN/ORDER BY/LIMIT Cypher syntax with a $tag parameter. The approach is documented to work for Neo4j, AWS Neptune, and Memgraph, since it targets the Cypher query language rather than a single vendor's specific driver.
When to use - and when NOT to
Use it when you already have data in a Cypher-compatible graph database - Neo4j, AWS Neptune, or Memgraph - and want to bring a specific, query-defined subset of it into LlamaIndex as documents. Use parameterized queries (via the parameters argument) rather than string-formatting values directly into the Cypher query. Do not use it as a general graph database administration tool; it is a read loader for turning query results into documents, not a way to write or modify the graph.
Capabilities
load_data runs a Cypher query (with optional parameters) against a Neo4j, AWS Neptune, or Memgraph endpoint and returns the nested results as LlamaIndex documents, rendered as a YAML representation of the result structure.
How to install
pip install llama-index-readers-graphdb-cypher
Requires a reachable GraphDB endpoint URI and, where required, a username and password - testable against Neo4j's public demo server or a free Neo4j Aura instance.
Who it's for
Developers who already store data in a Cypher-compatible graph database and want a specific, query-defined subset of it loaded into LlamaIndex for retrieval or question-answering.
Source README
Graph Database Cypher Loader
pip install llama-index-readers-graphdb-cypher
This loader populates documents from results of Cypher queries from a Graph database endpoint.
The user specifies a GraphDB endpoint URL with optional credentials to initialize the reader.
By declaring the Cypher query and optional parameters the loader can fetch the nested result docs.
The results will be turned into a yaml representation to be turned into a string for the document.
The approach should work for Neo4j, AWS Neptune and Memgraph.
Usage
Here's an example usage of the GraphDBCypherReader.
You can test out queries directly with the Neo4j labs demo server: demo.neo4jlabs.com or with a free instance https://neo4j.com/aura
import os
from llama_index.readers.graphdb_cypher import GraphDBCypherReader
uri = "neo4j+s://demo.neo4jlabs.com"
username = "stackoverflow"
[REDACTED]
database = "stackoverflow"
query = """
MATCH (q:Question)-[:TAGGED]->(:Tag {name:$tag})
RETURN q.title as title
ORDER BY q.createdAt DESC LIMIT 10
"""
reader = GraphDBCypherReader(uri, username, password, database)
documents = reader.load_data(query, parameters={"tag": "lua"})
This loader is designed to be used as a way to load data into LlamaIndex
and/or subsequently used as a Tool in a LangChain Agent.
It uses the Neo4j Graph Database for the Cypher queries.
FAQ
Common questions
Discussion
Questions & comments · 0
Sign In Sign in to leave a comment.