VereskLearn

Module 4 · Retrieval

Lesson 4.10

Graph retrieval

Graph retrieval stores facts as links between named things, then follows links to gather related facts.

Lesson 29 of 622 min read

The problem

Why it matters

Without it

A search finds the chunk that says "Basic plan includes Email support". It cannot reach the support hours, which sit in another chunk.

With it

Each fact is a link from one name to another. The system starts at a name and follows links for a set number of hops.

How it works

  • A fact is one link

    A fact has three parts: the name it starts from, a relation, and the name it points to. "Basic plan includes Email support" is one link with the relation includes. The example stores three links in this form.

    FromRelationTo
    Basic planincludesEmail support
    Pro planincludesPhone support
    Email supporthours9 to 5 weekdays
    The three stored links.
    // One stored fact: from, relation, and to.const edge = {  from: "Basic plan",  rel: "includes",  to: "Email support",};console.log(edge.from, edge.rel, edge.to);

    Output

    Basic plan includes Email support

  • A lookup table from each name

    A Map connects each name to the links that start there. Finding the links of one name is a single lookup, so the search does not scan every link. The map entry for Basic plan holds one link in this example.

    • Basic plan1 link: includes Email support
    • Pro plan1 link: includes Phone support
    • Email support1 link: hours 9 to 5 weekdays
    The map entry for each starting name.
    const edges = [  { from: "Basic plan", rel: "includes", to: "Email support" },  { from: "Pro plan", rel: "includes", to: "Phone support" },  { from: "Email support", rel: "hours", to: "9 to 5 weekdays" },];const graph = new Map<string, typeof edges>();for (const e of edges) {  graph.set(e.from, [...(graph.get(e.from) ?? []), e]);}console.log(graph.get("Basic plan"));

    Output

    [ { from: 'Basic plan', rel: 'includes', to: 'Email support' } ]

  • One hop reads the links of a name

    A hop is one move along a link. The walk starts at Basic plan, and one hop reads the links that start there. That hop finds "includes Email support" and the new name Email support.

    1. Basic plan
    2. includes
    3. Email support
    One hop from the starting name.
    const edges = [  { from: "Basic plan", rel: "includes", to: "Email support" },  { from: "Pro plan", rel: "includes", to: "Phone support" },  { from: "Email support", rel: "hours", to: "9 to 5 weekdays" },];const next = edges.filter((e) => e.from === "Basic plan");console.log(next.map((e) => e.from + " " + e.rel + " " + e.to));

    Output

    [ 'Basic plan includes Email support' ]

  • A second hop reaches the support hours

    The second hop starts at Email support, the name the first hop found. It reads one link, "hours 9 to 5 weekdays", which the first hop could not reach. Two hops return two facts in total.

    HopNames readFacts found
    1Basic plan1
    2Email support2 in total
    Facts found after each hop from Basic plan.
    const edges = [  { from: "Basic plan", rel: "includes", to: "Email support" },  { from: "Pro plan", rel: "includes", to: "Phone support" },  { from: "Email support", rel: "hours", to: "9 to 5 weekdays" },];const first = edges.filter((e) => e.from === "Basic plan");const names = first.map((e) => e.to);const second = edges.filter((e) => names.includes(e.from));console.log(second.map((e) => e.from + " " + e.rel + " " + e.to));

    Output

    [ 'Email support hours 9 to 5 weekdays' ]

  • Each link keeps its source

    A link in a real system also names the document and section it came from. An answer can then be checked against the original text. A link with no source cannot be verified, so it should not be trusted.

    Link alone

    • Basic plan includes Email support

    Link with source

    • Basic plan includes Email support
    • Source: plans page, section 2
    The same link with and without a source.

Full code

Read the program

See the full code

Common mistakes

What goes wrong

  • Too many hops. Each hop can pull in unrelated facts, so the answer grows noisy.
  • Storing facts without a source. A link with no source cannot be checked against its document.
  • Building the graph once by hand and never updating it. Stale links answer with old facts.

Use it when and skip it when

Is it the right tool?

Use it when

  • Questions ask how things connect, such as which plan includes which support.
  • Facts sit in separate chunks, and only a link joins them.

Skip it when

  • The answer is one sentence in one chunk. Vector search is enough.
  • Nobody maintains the links. The graph will go stale.

Words to know

Terms in this lesson

Node
A named thing in the graph, such as a plan.
Edge
A link between two nodes, with a relation name.
Hop
One step along an edge.
Triple
A fact written as from, relation, and to.
Full code