Complete Neo4j Tutorial: Graph Database for Knowledge Graphs and AI
Graph databases have become a critical component in modern AI application architecture, particularly for building knowledge graphs and Graph RAG (Retrieval-Augmented Generation) systems. Neo4j is the most popular graph database that allows us to model, store, and query data with complex relationships at high performance.
In this tutorial, we will learn Neo4j from basics to advanced usage, including how to integrate it with AI pipelines to build powerful knowledge graph systems.
Why Graph Databases?
Traditional relational databases store data in tables with rows and columns. When data has many relationships between entities, stacked JOIN queries become slow and difficult to maintain. Graph databases store data as nodes (entities) and relationships (edges), making relationship traversal a native, high-performance operation.
Use cases well-suited for graph databases:
- Knowledge graphs for AI and LLMs
- Social network analysis
- Fraud detection and anti-money laundering
- Recommendation engines
- Supply chain management
- Network and IT infrastructure mapping
Installation and Setup
Using Docker (Recommended)
The fastest way to run Neo4j is using Docker:
docker run -d \
--name neo4j \
-p 7474:7474 \
-p 7687:7687 \
-e NEO4JAUTH=neo4j/yourpasswordhere \
-e NEO4JPLUGINS='["apoc", "graph-data-science"]' \
-v neo4jdata:/data \
neo4j:5.latest
Port 7474 is for Neo4j Browser (web UI) and port 7687 is for the Bolt protocol (application connections).
Using Neo4j Desktop
Download Neo4j Desktop from the official Neo4j website to get a full GUI management tool. Neo4j Desktop provides features for creating multiple database instances, managing plugins, and running Cypher queries interactively.
Using Neo4j AuraDB (Cloud)
For production use or quick experimentation without local setup, Neo4j AuraDB provides a managed cloud service with a free tier sufficient for development.
Install Python Driver
pip install neo4j
For LangChain integration (optional):
pip install langchain-neo4j langchain-openai
Core Neo4j Concepts
Property Graph Model
Neo4j uses a property graph model consisting of:
- Nodes: Entities in the graph, having labels and properties
- Relationships: Connections between nodes, having a type and properties
- Labels: Categories for nodes (such as Person, Company, Product)
- Properties: Key-value pairs on nodes and relationships
Cypher Query Language
Cypher is the declarative query language for Neo4j. Here are the basic patterns:
// Create a node
CREATE (p:Person {name: 'Ruby Abdullah', role: 'Data Consultant'})
// Create a node with multiple labels
CREATE (c:Company:Organization {name: 'PT Rubythalib Data Konsulta', industry: 'AI Consulting'})
// Create a relationship
MATCH (p:Person {name: 'Ruby Abdullah'})
MATCH (c:Company {name: 'PT Rubythalib Data Konsulta'})
CREATE (p)-[:WORKSAT {since: 2024}]->(c)
// Query with pattern matching
MATCH (p:Person)-[:WORKSAT]->(c:Company)
RETURN p.name, c.name
Cypher patterns use intuitive ASCII art: () for nodes, --> for relationships, and [] for relationship details.
Basic Usage with Python
Connecting to the Database
from neo4j import GraphDatabase
URI = "bolt://localhost:7687"
AUTH = ("neo4j", "yourpasswordhere")
driver = GraphDatabase.driver(URI, auth=AUTH)
Verify connectivity
driver.verifyconnectivity()
print("Connection successful!")
CRUD Operations
def createperson(driver, name, role, skills):
query = """
CREATE (p:Person {name: $name, role: $role, skills: $skills})
RETURN p
"""
with driver.session() as session:
result = session.run(query, name=name, role=role, skills=skills)
record = result.single()
return record["p"]
def create
relationship(driver, personname, companyname, role):
query = """
MATCH (p:Person {name: $personname})
MATCH (c:Company {name: $companyname})
CREATE (p)-[r:WORKSAT {role: $role}]->(c)
RETURN p, r, c
"""
with driver.session() as session:
result = session.run(
query,
personname=personname,
companyname=companyname,
role=role
)
return result.single()
def findcolleagues(driver, personname):
query = """
MATCH (p:Person {name: $name})-[:WORKSAT]->(c:Company)<-[:WORKSAT]-(colleague:Person)
RETURN colleague.name AS name, colleague.role AS role
"""
with driver.session() as session:
result = session.run(query, name=personname)
return [{"name": r["name"], "role": r["role"]} for r in result]
Example usage
createperson(driver, "Alice", "ML Engineer", ["Python", "PyTorch"])
createperson(driver, "Bob", "Data Engineer", ["Spark", "Airflow"])
colleagues = findcolleagues(driver, "Alice")
for c in colleagues:
print(f"{c['name']} - {c['role']}")
Batch Operations with Transactions
For optimal performance when inserting large amounts of data, use explicit transactions:
def batchcreatenodes(driver, peopledata):
query = """
UNWIND $people AS person
CREATE (p:Person {
name: person.name,
role: person.role,
department: person.department
})
"""
with driver.session() as session:
session.run(query, people=peopledata)
people = [
{"name": "Alice", "role": "ML Engineer", "department": "AI"},
{"name": "Bob", "role": "Data Engineer", "department": "Data"},
{"name": "Charlie", "role": "Backend Developer", "department": "Engineering"},
{"name": "Diana", "role": "Product Manager", "department": "Product"},
]
batchcreatenodes(driver, people)
Building a Knowledge Graph
Knowledge graphs are one of the primary applications of Neo4j in the AI ecosystem. Let's build a simple knowledge graph for the AI technology domain.
Schema Design
def setupknowledgegraph(driver):
constraints = [
"CREATE CONSTRAINT IF NOT EXISTS FOR (t:Technology) REQUIRE t.name IS UNIQUE",
"CREATE CONSTRAINT IF NOT EXISTS FOR (c:Category) REQUIRE c.name IS UNIQUE",
"CREATE CONSTRAINT IF NOT EXISTS FOR (u:UseCase) REQUIRE u.name IS UNIQUE",
]
with driver.session() as session:
for constraint in constraints:
session.run(constraint)
print("Schema constraints created!")
setup
knowledgegraph(driver)
Populating the Knowledge Graph
def populateaiknowledgegraph(driver):
query = """
// Create categories
MERGE (ml:Category {name: 'Machine Learning'})
MERGE (dl:Category {name: 'Deep Learning'})
MERGE (nlp:Category {name: 'Natural Language Processing'})
MERGE (cv:Category {name: 'Computer Vision'})
MERGE (mlops:Category {name: 'MLOps'})
// Create technologies
MERGE (pytorch:Technology {name: 'PyTorch', type: 'framework', language: 'Python'})
MERGE (tf:Technology {name: 'TensorFlow', type: 'framework', language: 'Python'})
MERGE (transformers:Technology {name: 'HuggingFace Transformers', type: 'library', language: 'Python'})
MERGE (langchain:Technology {name: 'LangChain', type: 'framework', language: 'Python'})
MERGE (neo4jtech:Technology {name: 'Neo4j', type: 'database', language: 'Java'})
MERGE (mlflow:Technology {name: 'MLflow', type: 'platform', language: 'Python'})
MERGE (fastapi:Technology {name: 'FastAPI', type: 'framework', language: 'Python'})
// Create use cases
MERGE (rag:UseCase {name: 'RAG Pipeline'})
MERGE (kg:UseCase {name: 'Knowledge Graph'})
MERGE (chatbot:UseCase {name: 'AI Chatbot'})
MERGE (imgclass:UseCase {name: 'Image Classification'})
MERGE (objdet:UseCase {name: 'Object Detection'})
// Create relationships: Technology -> Category
MERGE (pytorch)-[:BELONGSTO]->(dl)
MERGE (tf)-[:BELONGSTO]->(dl)
MERGE (transformers)-[:BELONGSTO]->(nlp)
MERGE (langchain)-[:BELONGSTO]->(nlp)
MERGE (neo4jtech)-[:BELONGSTO]->(mlops)
MERGE (mlflow)-[:BELONGSTO]->(mlops)
// Create relationships: Technology -> UseCase
MERGE (langchain)-[:USEDIN]->(rag)
MERGE (neo4jtech)-[:USEDIN]->(kg)
MERGE (neo4jtech)-[:USEDIN]->(rag)
MERGE (transformers)-[:USEDIN]->(chatbot)
MERGE (pytorch)-[:USEDIN]->(imgclass)
MERGE (pytorch)-[:USEDIN]->(objdet)
// Create relationships: Technology -> Technology (dependencies)
MERGE (transformers)-[:DEPENDSON]->(pytorch)
MERGE (langchain)-[:INTEGRATESWITH]->(neo4jtech)
MERGE (langchain)-[:INTEGRATESWITH]->(transformers)
RETURN count() AS totaloperations
"""
with driver.session() as session:
result = session.run(query)
print("Knowledge graph populated!")
populateaiknowledgegraph(driver)
Querying the Knowledge Graph
def findtechnologiesforusecase(driver, usecasename):
query = """
MATCH (t:Technology)-[:USEDIN]->(u:UseCase {name: $usecase})
OPTIONAL MATCH (t)-[:BELONGSTO]->(c:Category)
RETURN t.name AS technology, t.type AS type, c.name AS category
"""
with driver.session() as session:
result = session.run(query, usecase=usecasename)
return [dict(r) for r in result]
def findtechnologyecosystem(driver, techname):
query = """
MATCH (t:Technology {name: $techname})
OPTIONAL MATCH (t)-[:DEPENDSON]->(dep:Technology)
OPTIONAL MATCH (t)-[:INTEGRATESWITH]->(int:Technology)
OPTIONAL MATCH (t)-[:USEDIN]->(u:UseCase)
OPTIONAL MATCH (t)-[:BELONGSTO]->(c:Category)
RETURN t.name AS technology,
collect(DISTINCT dep.name) AS dependencies,
collect(DISTINCT int.name) AS integrations,
collect(DISTINCT u.name) AS usecases,
collect(DISTINCT c.name) AS categories
"""
with driver.session() as session:
result = session.run(query, techname=techname)
return result.single()
Find technologies for RAG Pipeline
techs = findtechnologiesforusecase(driver, "RAG Pipeline")
for t in techs:
print(f" {t['technology']} ({t['type']}) - {t['category']}")
View LangChain ecosystem
eco = findtechnologyecosystem(driver, "LangChain")
print(f"\nLangChain ecosystem:")
print(f" Dependencies: {eco['dependencies']}")
print(f" Integrations: {eco['integrations']}")
print(f" Use cases: {eco['usecases']}")
Advanced Usage: Graph RAG with LangChain
Graph RAG combines the power of knowledge graphs with LLMs to produce more accurate and contextual answers. Unlike traditional vector RAG that only matches similarity, Graph RAG understands explicit relationships between entities.
Setting Up Neo4j Graph Store with LangChain
from langchainneo4j import Neo4jGraph, GraphCypherQAChain
from langchain
openai import ChatOpenAI
graph = Neo4jGraph(
url="bolt://localhost:7687",
username="neo4j",
password="yourpasswordhere"
)
print(graph.schema)
Creating a GraphCypherQAChain
GraphCypherQAChain allows an LLM to convert natural language questions into Cypher queries, execute them on Neo4j, and generate answers based on query results:
llm = ChatOpenAI(model="gpt-4o", temperature=0)
chain = GraphCypherQAChain.fromllm(
llm=llm,
graph=graph,
verbose=True,
allowdangerousrequests=True
)
response = chain.invoke({
"query": "What technologies are used for RAG Pipeline?"
})
print(response["result"])
response = chain.invoke({
"query": "What are the dependencies of HuggingFace Transformers?"
})
print(response["result"])
Building Hybrid RAG (Vector + Graph)
For the best results, combine vector search with graph traversal:
from langchainneo4j import Neo4jVector
from langchainopenai import OpenAIEmbeddings
embeddings = OpenAIEmbeddings()
vectorstore = Neo4jVector.fromexistinggraph(
embedding=embeddings,
url="bolt://localhost:7687",
username="neo4j",
password="yourpasswordhere",
nodelabel="Technology",
textnodeproperties=["name", "type", "language"],
embeddingnodeproperty="embedding"
)
def hybridsearch(driver, querytext, vectorstore, k=5):
# Step 1: Vector search to find relevant entities
vectorresults = vectorstore.similaritysearch(querytext, k=k)
entitynames = []
for doc in vectorresults:
if hasattr(doc, 'metadata') and 'name' in doc.metadata:
entitynames.append(doc.metadata['name'])
# Step 2: Graph traversal to enrich context
enrichmentquery = """
UNWIND $names AS name
MATCH (t:Technology {name: name})
OPTIONAL MATCH (t)-[r]->(related)
RETURN t.name AS source,
type(r) AS relationship,
labels(related)[0] AS relatedtype,
related.name AS relatedname
"""
with driver.session() as session:
result = session.run(enrichmentquery, names=entitynames)
graphcontext = [dict(r) for r in result]
return {
"vectorresults": vectorresults,
"graphcontext": graphcontext
}
Graph Data Science (GDS)
The Neo4j Graph Data Science Library provides graph algorithms for analytics and machine learning:
Community Detection
// Louvain Community Detection
CALL gds.graph.project(
'tech-graph',
'Technology',
{
INTEGRATESWITH: {orientation: 'UNDIRECTED'},
DEPENDSON: {orientation: 'UNDIRECTED'}
}
)
CALL gds.louvain.stream('tech-graph')
YIELD nodeId, communityId
RETURN gds.util.asNode(nodeId).name AS technology, communityId
ORDER BY communityId
Node Similarity
// Calculate similarity between technologies based on shared use cases
CALL gds.nodeSimilarity.stream('tech-graph')
YIELD node1, node2, similarity
RETURN gds.util.asNode(node1).name AS tech1,
gds.util.asNode(node2).name AS tech2,
similarity
ORDER BY similarity DESC
LIMIT 10
PageRank for Finding Most Influential Technologies
CALL gds.pageRank.stream('tech-graph')
YIELD nodeId, score
RETURN gds.util.asNode(nodeId).name AS technology, score
ORDER BY score DESC
LIMIT 10
Importing Data from Various Sources
Import from CSV
// Import nodes from a CSV file
LOAD CSV WITH HEADERS FROM 'file:///technologies.csv' AS row
CREATE (t:Technology {
name: row.name,
type: row.type,
language: row.language,
githubstars: toInteger(row.stars)
})
Import from JSON via Python
import json
def importfromjson(driver, jsonfile):
with open(jsonfile) as f:
data = json.load(f)
query = """
UNWIND $items AS item
MERGE (t:Technology {name: item.name})
SET t.type = item.type,
t.description = item.description,
t.language = item.language
WITH t, item
UNWIND item.categories AS cat
MERGE (c:Category {name: cat})
MERGE (t)-[:BELONGSTO]->(c)
"""
with driver.session() as session:
session.run(query, items=data["technologies"])
importfromjson(driver, "aitechnologies.json")
Best Practices
1. Schema Design
- Use specific and consistent labels (PascalCase for labels, UPPERSNAKECASE for relationship types)
- Create unique constraints for properties used as identifiers
- Avoid storing too much data as properties; consider splitting into separate nodes if the data has its own relationships
2. Query Optimization
// Create indexes for frequently queried properties
CREATE INDEX IF NOT EXISTS FOR (t:Technology) ON (t.type)
CREATE INDEX IF NOT EXISTS FOR (t:Technology) ON (t.language)
// Use PROFILE to view the query plan
PROFILE MATCH (t:Technology)-[:USEDIN]->(u:UseCase)
WHERE t.language = 'Python'
RETURN t.name, u.name
3. Connection Management in Python
from contextlib import contextmanager
from neo4j import GraphDatabase
class Neo4jConnection:
def init(self, uri, user, password):
self.driver = GraphDatabase.driver(uri, auth=(user, password))
def close(self):
self.driver.close()
def query(self, cypher, parameters=None):
with self.driver.session() as session:
result = session.run(cypher, parameters or {})
return [dict(record) for record in result]
def write(self, cypher, parameters=None):
with self.driver.session() as session:
result = session.executewrite(
lambda tx: tx.run(cypher, parameters or {}).data()
)
return result
Usage
conn = Neo4jConnection("bolt://localhost:7687", "neo4j", "password")
try:
results = conn.query("MATCH (n) RETURN count(n) AS total")
print(f"Total nodes: {results[0]['total']}")
finally:
conn.close()
4. Error Handling and Retry
from neo4j.exceptions import ServiceUnavailable, TransientError
import time
def executewithretry(driver, query, params=None, maxretries=3):
for attempt in range(maxretries):
try:
with driver.session() as session:
result = session.run(query, params or {})
return [dict(r) for r in result]
except (ServiceUnavailable, TransientError) as e:
if attempt == maxretries - 1:
raise
waittime = 2 attempt
print(f"Retry {attempt + 1}/{maxretries} after {waittime}s: {e}")
time.sleep(wait_time)
5. Monitoring and Maintenance
// Check database statistics
CALL db.stats.retrieve("GRAPH COUNTS")
// View all indexes
SHOW INDEXES
// View all constraints
SHOW CONSTRAINTS
// Delete orphan nodes (nodes without relationships)
MATCH (n)
WHERE NOT (n)--()
DELETE n
Conclusion
Neo4j is a powerful graph database for building knowledge graphs and graph-based AI systems. Here are the key takeaways from this tutorial:
Neo4j is an excellent choice to use alongside AI frameworks like LangChain and LlamaIndex for building systems that deeply understand relationships between data. With the growing popularity of Graph RAG and agentic AI, graph database management skills are becoming increasingly important for AI/ML practitioners.