Building a search that follows links instead of matching words
Animated steps and three labs you can run. Each lab builds a graph from five documents and answers one question with it.
- All 12 steps, read online
- Runnable labs to download (plain Python, runs offline)
- Free updates whenever it's revised
- 14-day refund (conditions)
Four questions this volume answers
Some questions are about something other than what they name: “what breaks if I change this?”, “what are we exposed to?”. The document with the answer shares no words with the question, and in all three labs it scored exactly zero, so no second ranking pass, more results or better embedding brings it up. If your questions are about the thing they name, stop here: ordinary search works and a graph is extra work.
Write 10 to 20 real questions first, list the kinds of things and links they need, and trace every question through that list on paper. Decide when two names are one thing with rules that refuse (“no two releases are one release”), not a similarity cutoff. Walk the graph with a hop limit and a node budget, and don't walk through very busy nodes. Write the found facts out grouped by node, with the source document on every line.
An empty answer has two causes that look the same: the walk never reached the answer (the hop limit), or reached it and dropped it (the node budget). They need opposite fixes. Merging two different things creates false facts and a tidier-looking graph; missing that two names are one leaves gaps nothing reports. And check what gets written out: a node that was kept but not written down is invisible to the model.
Don't build one if your things have no stable IDs, or your documents change faster than you can re-extract them: you'll serve out-of-date links as confidently as current ones. Budget for what you keep paying: the schema, re-extracting on every change, and name-matching rules that keep surprising you. A real graph database and embedding search for the starting point can come later without changing those decisions.
Introduction
Your search works, and your answers are still wrong. You ask “what breaks if I change this?”, “why did this start failing?” or “what are we exposed to?”, and you get back documents that look like the question, not the facts linked to it.
Why better search doesn’t fix it
The usual fix is better search: a better embedding model, a second ranking pass, more results, or words and embeddings combined. Those help when the answer is ranked too low.
- They can’t help when the answer scores zero.
- On questions like these, it often does. The document with the answer was written by someone who wasn’t thinking about your question, so it shares no words with it.
- In all three labs in this volume, the document with the answer scores exactly zero against the question.
That’s not a tuning problem. Seeing it as a different problem is most of what this volume is for.
What graph engineering is
Graph engineering means turning documents into a map of things and the links between them, so that a search can follow those links instead of looking for text that sounds like the question.
- Instead of storing whole documents, you pull out single facts. Each fact has three parts: a subject, a link and an object. This is called a triple.
- Facts that mention the same thing join up into one graph.
- A question starts at one thing and walks from link to link, reaching facts no single document puts together.
Where it fits with what you already have
It doesn’t replace your search. Finding where to start is still a search problem. The graph takes over after that first step.
| stage | what does it | where it stops |
|---|---|---|
| 1. find the starting point | your existing word or embedding search | at text that looks like the question; that’s all it can find |
| 2. walk outward | the graph, following links from there | at a hop limit you set (step 6) |
| 3. write it down | the facts the walk found, written as text | at the size of the request (step 7) |
Your search picks the starting point. The graph decides what comes with it.
Is this for you?
It depends on the kind of questions you ask, not on how many documents you have. Sort a few of your real ones:
| kind of question | example | what it needs |
|---|---|---|
| descriptive | “What does verify_signature do?” | text that looks like it; you don’t need this volume |
| descriptive | “Summarize the incident report.” | text that looks like it; a graph is extra work here |
| connective | “What breaks if I change verify_signature?” | links: the answer is about a different thing |
| connective | “Why did this test start failing?” | links: the cause is a few steps from the symptom |
| connective | “Which products are exposed to this outage?” | links: the two ends share no words |
What it costs
A graph costs three things: a fixed list of the kinds of things and links you allow, which someone has to keep up to date; a pass over every document to pull the facts out; and a rule for deciding when two names mean the same thing. The last one is the hard part, and step 5 is about it.
What you’ll get
- A way to tell which of your questions need links rather than lookalike text.
- The eight stages of a graph search, and the five decisions inside them.
- Three labs you can run on your own computer. The next section explains them.
The labs: what they are
Each lab is a small Python program you download and run yourself. Once you own the volume, the Download the labs button at the top of this page gives you all three in one zip. Each lab builds a graph from five documents and answers one question with it:
- Test triage: why did a test start failing, and who should I ask?
- Code change: if I change this function, what breaks, and who should review it?
- Supply chain: which of our products are exposed to a flood, and which aren’t?
What you do in the labs
- Try ordinary search first, and watch the document with the answer score zero.
- Pull facts out of the documents, and see which ones get refused and why.
- Decide which names are the same thing, and which only look alike.
- Walk the graph to the answer, then change the hop limit or budget and watch it fail.
What you’ll learn
- Why some questions can’t be answered by text that looks like them.
- How refusing bad facts and bad merges keeps a graph trustworthy.
- Why “never reached” and “found, then dropped” look the same and need opposite fixes.
- When a graph is worth building, and when it isn’t.
Two ways to run them
| way | what pulls facts out and answers | what it costs | the results |
|---|---|---|---|
| scripted | a built-in stand-in, the same every time | free, and works offline | the same every run. These pages quote them. |
| live | a real model: Claude through the API, Claude Code, or an OpenAI model | real calls: you pay per call, or it uses your Claude Code plan | close to these pages, and a little different each run |
All three labs can run either way.
Before a live run
- Run the setup script in the labs folder. It installs everything a live run needs.
- Pick a model and put its key in the settings file,
labs/.env. For Claude Code you need no key. The labs’ README shows every line. - Check the connection with one tiny call. It costs well under a cent.
- Start the run. Before sending anything, it shows how many calls it will make and what they should cost, and waits for you to type yes. A spending cap stops the run if costs go over, and every answer is saved, so you never pay twice for the same request.
Where the ideas come from
The search half (the size tables, the hop sweep and every measured figure) is this volume’s own. The building half follows an established course, and each step that borrows from it links to it there. The full list is at the end of step 12.
How to read the labels
Each step has a label that tells you where its content comes from.
| label | means |
|---|---|
| concept | explained from first principles; no lab numbers |
| demonstrated | a lab shows how it works, with its own output |
| measured | a lab compares two approaches and reports the difference |
| lab | a guided lab you run yourself, step by step |
| your own text | how to use the method on your own documents |