Knowledge Graph Primitives & Graph RAG with Neo4j

Hand-copyable revision sheet#

Telegraphic. Copy straight into your notebook. Everything here is derived from the Detailed Notes below.

The complete reference#

01Revision — the Alpha Fund hybrid tool-calling dashboard #

Before graphs, a recap of the Week-4/5 project so the pieces connect. The Alpha Fund Intelligence dashboard is a Streamlit app that answers questions about financial data by picking the right retrieval tool for each query.

It pairs BM25 — the "find the exact word" method (lexical search, ideal for precise things like a transaction ID) — with FAISS — the "find the thing that means the same" method (semantic/contextual search over embeddings). BM25 catches exact matches; FAISS catches meaning.

How the tool calling actually works#

LangChain's bind_tools() attaches your functions to the model. Here there are two: query_sp500_financials (runs SQL against an S&P 500 financials table) and search_earnings_transcript (does a similarity search over 2024 earnings-call transcripts stored in FAISS). The LLM reads the request and routes to one, the other, or both.

The orchestration loop#

The run_agent function is a while True loop implementing agentic reasoning: the LLM calls a tool, observes the result, appends it to the message list, then decides whether it needs another tool. When ai_message.tool_calls comes back empty (None), it stops and emits the final HumanMessage/answer. A single-tool question iterates ~twice (call, then confirm done); a "boss fight" query that hits both tools iterates more.

Other mechanics worth remembering: temperature=0 for deterministic, context-faithful answers; a fallback model (GPT-4o-mini) if the chosen OpenRouter model has no endpoint; the FAISS index built with all-MiniLM-L6-v2 embeddings and a recursive splitter (chunk_size=600, overlap=80); and executemany to bulk-insert SQL rows in one shot.

02The relational blind spot — why FAISS and SQL both break #

Take the motivating query again: "Who is the CEO of the parent company that recently acquired the startup Tony mentioned in his Q3 compliance report?" This is a multi-hop question — the answer isn't in one chunk or one row; you have to hop across several linked facts. Both existing tools collapse on it, for different reasons.

Failure 1 — FAISS has no sense of direction#

When FAISS embeds the query, it breaks it into semantic pieces — CEO, parent company, acquired, startup, Q3 compliance — and pulls back chunks that each resemble one of those pieces: a chunk saying "Microsoft acquired Nuance," another saying "Tony submitted the Q3 report on Friday." All true, all relevant-looking, all disconnected.

Failure 2 — SQL chokes on deep multi-hop mapping#

SQL is brilliant at aggregation (sum, min, max over rows) but a nightmare at deep relationship mapping. To answer the question, the LLM must generate something like: SELECT name FROM executives JOIN companies … JOIN acquisitions … JOIN companies … JOIN reports … JOIN employees … — five hops, five JOINs.

03The graph paradigm — precomputed connectivity#

You store facts as triples — subject → predicate → object (e.g. Tony — WROTE — Q3 report). The relationships are precomputed and physically stored on the hard drive, so they already exist before any question is asked. This is the opposite of SQL, where the LLM generates a query and the JOINs (the relationships) are assembled at runtime.

When the AI queries the graph it doesn't scan millions of rows. It lands on the node (say, Tony) and walks the edges to neighboring nodes — physically hopping node → edge → node. That walk finishes in milliseconds and the output is deterministic, 100% accurate: it arrives exactly at Executive: Satya Nadella.

04The Labeled Property Graph (LPG) model#

Everything in Neo4j reduces to three primitives. Learn these three and the rest is syntax.

Properties are schema-free: they aren't locked to a fixed column set, and different nodes of the same label can carry different properties. A Company node might hold {name, ticker:"MSFT", market_cap}; a Document node might hold {title:"Q4 transcript"}. Edges can have properties too — e.g. a WORKS_FOR edge can carry {role:"analyst"}.

05Cypher — "SQL for graphs"#

Think of it as SQL for graphs. Its syntax is visual — the punctuation looks like the thing it represents.

Inside a node you attach a label, an alias (a temporary variable, exactly like a SQL table alias), and properties in curly braces:

(e:Executive {name:'Tony'})
 │   │            │
 │   │            └─ property  (find the node whose name = Tony)
 │   └─ label      :Executive
 └─ alias e  (reuse it later, like a SQL alias)

The same for an edge — alias, type, and optional properties:

-[w:WORKS_FOR {role:'analyst'}]->
   │    │            │
   │    │            └─ edge property
   │    └─ relationship type
   └─ alias w

The two core reading commands: MATCH and RETURN#

MATCH is the Cypher equivalent of SQL's SELECT — it searches the database for a specific geometric pattern. RETURN names the output columns.

Example scenario: "every company mentioned in the Q3 compliance report."

MATCH (d:Document {title:'Q3 compliance report'})-[:MENTIONS]->(c:Company)
RETURN c.company_name

The full multi-hop query#

Now the original question becomes one readable pattern. Each hop is another -[edge]->(node) segment:

MATCH (e:Executive {name:'Tony'})-[:WROTE]->(d:Document) -[:MENTIONS]->(startup:Company) -[:ACQUIRED_BY]->(parent:Company)
MATCH (e2:Executive)-[:WORKS_FOR {role:'CEO'}]->(parent)
RETURN e2.name // parent CEO, parent.name
// → "Satya Nadella", "Microsoft"  ·  executes in ~5 ms

06MERGE vs CREATE — the ingestion trap#

When you build the graph, an LLM reads many documents and extracts entities. Suppose it reads 50 news articles and encounters "Microsoft" 20 times. How you write those 20 mentions decides whether your graph is usable.

07Graph RAG architecture — the hybrid pipeline#

Crucially, you don't throw away FAISS. It's a hybrid: each tool does the part it's best at.

1. FAISS finds the starting node. Out of 10,000 employees, vector search pinpoints the exact "Tony" node the question refers to. This is the one thing vectors are great at — fuzzy entry matching.
2. Graph traversal pulls the neighborhood. Once landed, walk the graph to pull every connected entity within an N-hop radius (here, 2 hops). This gathers the linked companies, documents, and executives the question needs.
3. Hand the subgraph to the LLM. That small, connected subgraph — not a pile of loose chunks — becomes the context. The LLM reads a coherent web and produces the answer.

08Deployment — Docker, ports, APOC, safe ingestion#

Why Docker at all#

If the database disappears every time you restart Python, "you're building a toy, not an application." The graph DB should run independently of your code, accept secure connections, and persist data. You define it in a docker-compose.yml — infrastructure as code — so every developer gets an identical environment, and you can later ship the same container to an EC2 instance or Kubernetes without "works on my machine" problems.

Volumes — the "hole in the ship"#

Containers are ephemeral: if the container crashes, everything inside is deleted. Volume mounts map container folders to your local hard drive so the data survives. A helpful image: you "drill a hole in the Docker ship" so the Neo4j data leaks out onto your laptop and persists even if you destroy the container.

The two ports#

Bolt is the graph analog of using psycopg/SQLite to connect a relational DB to Python. Any LangChain agent or Python script talks to Neo4j over 7687, with auth (user neo4j + password).

APOC — the LLM bridge#

Neo4j is a pure graph database, but LLM integration needs data passed as JSON. APOC handles that string manipulation and can run complex procedures, converting nodes/edges to/from JSON when building the Graph RAG database. You enable it with a plugin setting so Docker auto-downloads and installs it on boot.

Safe ingestion — parameterized Cypher#

# parameterized — safe
query = "MERGE (e:Executive {name: $author})"
graph_db.execute_write(query, {"author": "Tony"})

To enforce clean structure, add uniqueness constraints — the graph equivalent of a SQL primary key. Declaring company, executive, and document unique guarantees Microsoft can't be created twice, locking in the MERGE behavior at the schema level. Reads use an execute_read function (like SELECT); writes use execute_write (a DDL-style command that creates data via CREATE/MERGE).

Follow-up questions this material invites#

Tap a question to reveal a 2–4 sentence answer you can read aloud.