Study Guide · Session Notes

Knowledge Graph Primitives & Graph RAG with Neo4j

Why vector search and SQL both break on "who is the CEO of the parent company that acquired the startup Tony mentioned?" — and how a labeled property graph, Cypher, and a hybrid Graph RAG pipeline answer it in milliseconds. Includes a revision of the Alpha Fund hybrid tool-calling dashboard.

Graph RAG · Revision Neo4j · Cypher · APOC Graph RAG · LPG model Tool calling · LangChain Neo4j · Cypher

Section 1 — Notebook Summary

Hand-copyable revision sheet

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

---

Section 2 — Detailed Study Notes

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.

A hybrid engine is a search system that runs two complementary retrieval methods and combines their strengths.

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

Tool calling is letting the LLM decide which of several functions to run, based on the user's question.

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

A knowledge graph stores data as a web of relationships that are computed once and saved to disk, not rebuilt for every query.

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

The Labeled Property Graph is the data structure Neo4j is built on: a system of nodes, edges, and properties.

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"

Cypher is Neo4j's query language: it describes the shape of the data you want, and the engine walks the graph to find it.

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.

CREATE always makes a brand-new node; MERGE finds an existing node or creates it only if absent (an upsert).

07Graph RAG architecture — the hybrid pipeline

Graph RAG uses vector search to find where to start, then graph traversal to gather the connected context, then hands that subgraph to the LLM.

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

Docker runs Neo4j as an independent, reproducible service so your database doesn't vanish when your Python kernel restarts.

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

APOC (Awesome Procedures On Cypher) is a Neo4j plugin that adds utilities — critically, JSON parsing needed to integrate the graph with LLMs.

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).

---

Interview & Practice

Follow-up questions this material invites

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

Q1Why do vector databases fail on multi-hop relationship questions?▸

Vectors encode similarity, so cosine similarity measures distance, not lineage. FAISS returns individually-relevant chunks but has no mathematical way to know that "this Microsoft" is the parent of "that startup." The LLM receives disconnected facts with no directional link, so it can't reliably chain them.

Q2SQL can express joins — why is it a poor fit for deep multi-hop queries?▸

SQL excels at aggregation but computes JOINs at runtime. A five-hop question means five JOINs scanning and cross-referencing potentially millions of rows — computationally catastrophic on large datasets. It's also fragile: the LLM must guess the schema perfectly, and one wrong foreign key silently returns zero rows.

Q3What are the three primitives of the Labeled Property Graph model?▸

Nodes (nouns/entities with labels, e.g. :Company), edges (verbs — directional relationships like ACQUIRED), and properties (schema-free key–value metadata that can sit on either a node or an edge). Neo4j is built entirely on these three.

Q4In Cypher, what's the difference between MATCH and MERGE?▸

MATCH is read-only — the equivalent of SQL SELECT, finding an existing geometric pattern. MERGE is an upsert: it looks for a node and binds to it if found, or creates it if not. MATCH queries the graph; MERGE safely builds it without duplicates.

Q5Why use MERGE instead of CREATE during ingestion?▸

CREATE always makes a new node, so extracting "Microsoft" 20 times yields 20 disconnected duplicates and a shattered, un-traversable graph. MERGE guarantees a single canonical node that acts as a hub, letting every document and executive connect to the same Microsoft. Pair it with uniqueness constraints to enforce this at the schema level.

Q6Walk through the Graph RAG pipeline end to end.▸

First, FAISS vector search finds the starting node (e.g. the right "Tony" among thousands). Second, graph traversal walks a fixed hop radius (say 2 hops) to pull every connected entity. Third, that coherent subgraph — not loose chunks — is handed to the LLM, which produces the final answer. Vectors handle entry; the graph handles relationships.

Q7What do ports 7474 and 7687 do, and why two?▸

7474 is the HTTP port for the Neo4j browser — a visual UI for humans to draw graphs and write Cypher manually. 7687 is the Bolt port, a binary protocol for machines; any Python script or LangChain agent connects through it, analogous to a database driver like psycopg for Postgres.

Q8What is APOC and why is it needed for LLM integration?▸

APOC (Awesome Procedures On Cypher) is a Neo4j plugin adding utilities like string manipulation and complex procedures. It's essential for LLM work because it handles JSON parsing — you can't pass graph data to an LLM directly, so APOC serializes nodes and edges to and from JSON. It's installed automatically on container boot via a plugin setting.

Q9Why parameterize Cypher queries instead of using f-strings?▸

Building Cypher with Python f-strings opens a Cypher-injection vulnerability, the direct analog of SQL injection — a crafted input could delete or exfiltrate data. Passing values as isolated parameters keeps the query structure fixed and the data separate, which is standard MLOps security practice.

---

Recap

"""Chapter 05 — a mini query layer + community detection over the Graph.

Cypher is just pattern matching: find nodes by label/property, then walk a
named relationship. Communities are connected components — clusters that talk
to each other more than to the rest of the graph.
"""
from atlas.graph import Graph, seed_graph


def match(g, label=None, **props):
    """MATCH (n:Label {prop: value}) — return matching node ids."""
    hits = []
    for id, data in g.nodes.items():
        if label and data.get("label") != label:
            continue
        if all(data.get(k) == v for k, v in props.items()):
            hits.append(id)
    return hits


def walk(g, start, rel):
    """MATCH (start)-[rel]->(x) RETURN x — one hop along a named edge."""
    return [dst for r, dst in g.out[start] if r == rel]


def communities(g):
    """Connected components over the undirected graph = graph communities."""
    parent = {id: id for id in g.nodes}

    def find(x):
        while parent[x] != x:
            parent[x] = parent[parent[x]]
            x = parent[x]
        return x

    for src in g.nodes:
        for _, dst in g.out[src]:
            parent[find(src)] = find(dst)

    groups = {}
    for id in g.nodes:
        groups.setdefault(find(id), []).append(id)
    return sorted(groups.values(), key=len, reverse=True)


if __name__ == "__main__":
    g = seed_graph()
    print("Companies:", match(g, label="Company"))
    print("Who does Elena work for?", walk(g, "Elena", "works_for"))
    print("Communities:")
    for i, c in enumerate(communities(g), 1):
        print(f"  {i}: {sorted(c)}")

Companies: ['Microsoft', 'Alpha', 'Nimbus']
Who does Elena work for? ['Nimbus']
Communities:
  1: ['Alpha', 'Elena', 'Microsoft', 'Nimbus', 'Q3 Report', 'Tony']