Building a Neo4j Knowledge Graph: Entity Modeling, Cypher Queries, and LangChain Integration

Why graph databases excel at relationship‑intensive queries

Relational databases need multi‑table JOIN statements; for example, finding all managers of engineers who worked on payment projects in 2025 requires three tables and degrades sharply as data grows. Neo4j stores entities and relationships as first‑class citizens, so a single Cypher statement can traverse any depth with linear time complexity.

Core advantage : relational databases – exact queries, transactions; vector stores – semantic similarity; Neo4j – native relationship‑path traversal.

Query language : SQL, ANN nearest‑neighbor, Cypher path matching.

Multi‑hop joins : JOIN with exponential slowdown (relational), not supported (vector), native linear growth (Neo4j).

Fuzzy search : LIKE with low efficiency (relational), strong vector‑based (vector), weak without vector supplement (Neo4j).

Best fit : structured transactional data (relational), semantic retrieval (vector), knowledge graphs and relationship networks (Neo4j).

Core concepts: Node, Relationship, Property

Node : an entity such as an engineer, project, or technology. Example: (e:Engineer {id: "E001", name: "张三", level: "P7"}) Relationship : a directed, typed edge that can carry properties. Example:

(e:Engineer)-[:WORKED_ON {since: "2024-01", role: "lead"}]->(p:Project)

Property : key‑value pairs attached to nodes or relationships.

(张三:Engineer)──[WORKED_ON]──> (payment服务:Project)
        |                     |
[REPORTS_TO]               [USES_TECH]
        ↓                     ↓
(李总:Manager)          (TypeScript:Technology)

Environment setup: Docker + TypeScript / Python connection

docker run \
  --name neo4j -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/your-password \
  -v $PWD/neo4j-data:/data \
  -d neo4j:5.18

TypeScript driver:

import neo4j from "neo4j-driver";
const driver = neo4j.driver(
  "bolt://localhost:7687",
  neo4j.auth.basic("neo4j", "your-password")
);
const info = await driver.getServerInfo();
console.log("Connected to:", info.address);
console.log("Neo4j version:", info.agent);

Python driver:

from neo4j import GraphDatabase

driver = GraphDatabase.driver(
    "bolt://localhost:7687",
    auth=("neo4j", "your-password")
)
with driver.session() as session:
    result = session.run("RETURN 1 AS n")
    print("Connected! Result:", result.single()["n"])

Cypher in practice: six high‑frequency patterns

Pattern 1 – MERGE (idempotent upsert)

await session.run(`
  MERGE (e:Engineer {id: $id})
  ON CREATE SET e.name = $name, e.level = $level, e.createdAt = datetime()
  ON MATCH SET e.level = $level, e.updatedAt = datetime()
  RETURN e
`, {id: "E001", name: "张三", level: "P8"});

Pattern 2 – Variable‑length path query

await session.run(`
  MATCH (e:Engineer {id: $id})-[:WORKED_ON*1..2]->(p:Project)
  RETURN DISTINCT p.name AS project, p.status
`, {id: "E001"});

Pattern 3 – UNWIND for bulk writes (≈10× speedup)

await session.run(`
  UNWIND $engineers AS eng
  MERGE (e:Engineer {id: eng.id})
  ON CREATE SET e.name = eng.name, e.level = eng.level
`, {engineers: [
    {id: "E002", name: "李四", level: "P6"},
    {id: "E003", name: "王五", level: "P8"}
  ]});

await session.run(`
  UNWIND $assignments AS assign
  MATCH (e:Engineer {id: assign.engineerId})
  MATCH (p:Project {id: assign.projectId})
  MERGE (e)-[r:WORKED_ON {role: assign.role}]->(p)
  SET r.since = assign.since
`, {assignments: [
    {engineerId: "E001", projectId: "P001", role: "lead", since: "2024-01"},
    {engineerId: "E002", projectId: "P001", role: "backend", since: "2024-03"}
  ]});

Additional patterns cover CREATE vs MERGE trade‑offs, batch relationship creation, and enforcing LIMIT on result sets.

LangChain integration: LLM auto‑generates Cypher

Initialize a Neo4jGraph, refresh the schema, and provide a custom prompt that forces read‑only queries, preserves relationship direction, uses CONTAINS for string comparison, and appends LIMIT 50.

import { Neo4jGraph } from "@langchain/community/graphs/neo4j_graph";
import { ChatOpenAI } from "@langchain/openai";
import { GraphCypherQAChain } from "@langchain/community/chains/graph_qa/cypher";
import { PromptTemplate } from "@langchain/core/prompts";

const graph = await Neo4jGraph.initialize({
  url: "bolt://localhost:7687",
  username: "neo4j",
  password: "your-password",
});
await graph.refreshSchema();

const cypherPrompt = PromptTemplate.fromTemplate(`
You are a Neo4j expert. Generate an exact READ‑only Cypher query based on the schema.
Schema: {schema}
Rules:
1. Only MATCH/RETURN, no writes.
2. Preserve relationship direction.
3. Use CONTAINS for string comparison.
4. Append LIMIT 50.
Question: {question}
Cypher query:
`);

const chain = GraphCypherQAChain.fromLLM({
  llm: new ChatOpenAI({ modelName: "gpt-4o", temperature: 0 }),
  graph,
  cypherPrompt,
  verbose: true,
  returnDirect: false,
});

const result = await chain.invoke({ query: "负责 payment 服务的工程师有哪些?他们的 level 是什么?" });
console.log(result.result);

Generated Cypher (verbose mode):

MATCH (e:Engineer)-[r:WORKED_ON]->(p:Project)
WHERE p.name CONTAINS 'payment'
RETURN e.name, e.level, r.role
LIMIT 50

Production‑grade modeling: technical‑team knowledge graph

Identify entities: Engineer, Project, Technology, Team.

Define directed relationships (e.g., REPORTS_TO, BELONGS_TO, WORKED_ON, USES_TECH, SKILLED_IN).

Create uniqueness constraints for primary keys.

Bulk‑load nodes and relationships with UNWIND and MERGE.

await session.run(`
  CREATE CONSTRAINT IF NOT EXISTS FOR (e:Engineer) REQUIRE e.id IS UNIQUE
`);
await session.run(`
  UNWIND $engineers AS eng
  MERGE (e:Engineer {id: eng.id}) SET e += eng
`, {engineers: [
    {id: "E001", name: "张三", level: "P7", joinDate: "2022-03"},
    {id: "E002", name: "李四", level: "P6", joinDate: "2023-06"}
  ]});

After loading, Neo4j Browser visualizes a dense network of engineers, projects, technologies, and teams.

Common pitfalls

Direction mismatch : Using the wrong arrow direction returns no data. Use undirected -[:REL]- only for debugging.

CREATE vs MERGE : Re‑running scripts with CREATE duplicates nodes; prefer MERGE for idempotent upserts.

Case‑sensitive relationship types : WORKED_ON and worked_on are distinct; enforce consistent uppercase.

Missing indexes : Queries like MATCH (e:Engineer {name: '张三'}) scan all nodes; create indexes on frequently queried properties.

Forgotten LIMIT : LLM‑generated queries without LIMIT can exhaust memory; enforce LIMIT 50 in the prompt.

Storing large text in nodes : Keep relationship structure in the graph and raw documents in a vector store, linking via IDs.

Summary

Graph databases outperform relational databases for multi‑hop relationship queries; joins cause exponential slowdown.

Neo4j’s three primitives (node, relationship, property) make relationships first‑class citizens.

Six high‑frequency Cypher patterns—MERGE, UNWIND, variable‑length paths, batch relationship creation, and LIMIT enforcement—are essential for production.

LangChain’s GraphCypherQAChain lets an LLM generate accurate Cypher when temperature is 0 and the prompt constrains output.

Modeling principle: store relationship topology in Neo4j, store large textual content in a vector database, and link them via IDs.

Check the six common pitfalls (direction, MERGE vs CREATE, case sensitivity, missing indexes, missing LIMIT, oversized node payloads) before deployment.