Advanced Indexing: Parent-Child Documents, Summary Indexes, Contextual Retrieval, and the Trade-Offs of Tree Aggregation vs. Graph Retrieval

Parent-child indexes: the retrieval unit and the context unit need not be the same

Day four's chunking left one sentence hanging: small chunks retrieve precisely, large chunks give complete context, and can we have both. The answer is yes, by making them different things.

Cut by heading node into large chunks called parents, and cut a parent into 200-character small chunks called children. Only children enter the index, with parents kept aside and hung by parentId; retrieval hits a child and context assembly swaps it for its parent — like a catalog card reading "row 3, slot 2" while what you fetch by the card is a whole book.

Child (indexed, 200 chars)  →  hit  →  swapped by parentId for the parent (into context, a whole section)

// A parent = one heading node; a child = that section cut into 200-character pieces
export function chunkParentChild(doc) {
  const children = []
  const parents = new Map()
 
  doc.nodes.forEach((node, i) => {
    const parentId = `${doc.docId}#p${String(i + 1).padStart(2, '0')}`
    const heading = node.headingPath.join(' > ')
    parents.set(parentId, { chunkId: parentId, text: `${heading}\n${node.text}` })
 
    // A child's head also carries the heading path, matching the flat-chunk convention
    for (const part of splitLong(node.text, 200, 40)) {
      children.push({
        docId: doc.docId,
        chunkId: `${doc.docId}#k${String(children.length + 1).padStart(2, '0')}`,
        text: `${heading}\n${part}`,
        parentId, // the key: a child knows which parent it belongs to
      })
    }
  })
  return { children, parents }
}

from dataclasses import dataclass
 
@dataclass
class Chunk:
    doc_id: str
    chunk_id: str
    text: str
    parent_id: str | None = None
 
def chunk_parent_child(doc) -> tuple[list[Chunk], dict[str, Chunk]]:
    """A parent = one heading node; a child = that section cut into 200-character pieces"""
    children: list[Chunk] = []
    parents: dict[str, Chunk] = {}
 
    for i, node in enumerate(doc.nodes, start=1):
        parent_id = f"{doc.doc_id}#p{i:02d}"
        heading = " > ".join(node.heading_path)
        parents[parent_id] = Chunk(doc.doc_id, parent_id, f"{heading}\n{node.text}")
 
        # A child's head also carries the heading path, matching the flat-chunk convention
        for part in split_long(node.text, 200, 40):
            children.append(
                Chunk(
                    doc_id=doc.doc_id,
                    chunk_id=f"{doc.doc_id}#k{len(children) + 1:02d}",
                    text=f"{heading}\n{part}",
                    parent_id=parent_id,  # the key: a child knows which parent it belongs to
                )
            )
    return children, parents

What is easy to get wrong is not the cutting but the assembly. One parent is often hit by several children, and stuffing them in by rank puts the same passage in three times, exhausting a 600-token budget on two chunks. So deduplicate parents, and skip a duplicate by continuing to the next entry rather than stopping — other parents wait behind it.

The cost is more index entries (134 chunks becoming 158 on this corpus) and larger pieces entering the context: trading index volume and context budget for chunk completeness, not something for nothing.

A caution: this evaluation set cannot measure parent-child indexing's benefit. Single-document recall is already 100% under every configuration, and the material completeness parent-child restores does not show in a binary did-the-answer-document-enter metric. Matching the baseline does not mean it is useless, only that this ruler cannot measure it — that needs a different ruler, such as a model judge deciding whether the material suffices.

Summary indexes: locate the book first, then the page

The second catalog is for many long documents: generate a hundred-word summary per document and index only the summaries. A query searches the summaries first, locates the three to five most relevant documents, and then searches finely within those.

The benefit is direct: ten thousand documents make hundreds of thousands of chunk-level entries and only ten thousand summary entries; in production the second stage needs no separate index, since a vector store filter on document id suffices.

And it is a net loss on our corpus: baseline recall 93.8% against the summary index's 87.5%; multi-hop falls from 75% to 50% and the answer document's average rank retreats from 2.44 to 3.63.

The first stage keeps only three documents, and if either of a multi-hop question's two documents looks irrelevant at the summary level, it is cut in stage one and no accuracy in stage two recovers it. The computation it saves is paid for entirely by stage one possibly cutting wrongly. Remember the criterion as one sentence: a summary index starts paying off only once the document count makes whole-store chunk-level retrieval itself the bottleneck; before that it merely manufactures a recall ceiling for itself.

Contextual retrieval: add a locating line per chunk, then look honestly at the numbers

The third catalog is the most widely circulated technique lately, and its method is one line: have the model read the whole document and write, for each chunk, one line saying which part of the document it is, prefixed to the chunk before indexing.

"The retention period is 30 days" alone tells nobody whose retention period; prefix "Drive and File Management, Recycle Bin:" and a query about how long the recycle bin keeps things can match it.

// The cache breakpoint goes after the whole document: from the second chunk on you pay only the cache read price
const res = await client.messages.create({
  model: 'claude-sonnet-5',
  max_tokens: 100,
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: `Full text:\n${doc.body}`, cache_control: { type: 'ephemeral' } },
        { type: 'text', text: `One passage from it:\n${chunk.text}\n\n${INSTRUCTION}` },
      ],
    },
  ],
})
// The header goes only into the indexed text, never into the text entering the context
const indexText = `${res.content[0].text.trim()}:\n${chunk.text}`

# The cache breakpoint goes after the whole document: from the second chunk on you pay only the cache read price
res = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=100,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": f"Full text:\n{doc.body}",
                    "cache_control": {"type": "ephemeral"},
                },
                {"type": "text", "text": f"One passage from it:\n{chunk.text}\n\n{INSTRUCTION}"},
            ],
        }
    ],
)
# The header goes only into the indexed text, never into the text entering the context
index_text = f"{res.content[0].text.strip()}:\n{chunk.text}"

The order cannot be reversed: caching matches by prefix, so the whole document comes first; put per-chunk content first and the prefix changes every time and the cache never hits.

Now the numbers. Day four measured a counter-intuitive result under pure BM25: adding headers left the hit rate unchanged, raised index tokens by a tenth, and pushed the answer document's average rank back from 2.88 to 3.25. The explanation was that a header spreads a document's heading terms across every chunk, lowering their own inverse document frequency and diluting keyword retrieval; and the note then was that its benefit should be on the vector side. Today settles that bill.

Split context into three levels and run each on three retrieval routes (30 documents, a 20-question golden set, chunk-level retrieval, a 600-token budget, offline hash vectors):

① is a bare chunk, ② is a chunk whose head carries the heading path, and ③ is a chunk with a generated header. Index tokens go from 15,638 to 18,036 to 22,339 along the way. ② corresponds to day nine's configuration, except the heading path is prefixed once — day nine's implementation prefixed it twice, so this chapter's absolute numbers are not strictly comparable with days eight and nine, and only relative differences within this chapter should be read.

Three conclusions, each less like marketing than the last:

First, the vector route rises on its own, and that rise proves nothing. Pure vector recall goes from 81.3% to 87.5% and nDCG@10 from 0.5088 to 0.6185. The problem is that offline mode's "vector" is a hash vector preserving literal overlap — its rise shows only that the header added more literally matchable words, not that a real embedding becomes more accurate for having semantic context. Those two look alike and are not the same thing.

Second, day four's rank regression did not reproduce. Pure BM25's average rank is 2.44 at all three levels. The difference is the chunking: day four hard-cut at 400 characters so boundaries did not align with sections and headers pulled in heading terms not belonging to that chunk; today cuts by heading node, so a chunk sits inside one section and the header overlaps heavily with what it already has. So the conclusion is not that headers harm BM25 but that they harm it when chunk boundaries do not align with structure — the precondition matters more than the conclusion.

Third, on the hybrid route, headers buy ranking quality and not recall. Recall stays at 93.8% and the answer document's average rank stays at 2.44, with only nDCG@10 rising from 0.6438 to 0.7218. Pick the wrong metric and this whole passage gives the opposite conclusion: watching nDCG alone suggests a 12.1% gain, and watching recall alone suggests it did nothing.

Costs go in two ledgers, and this is the section's most practical passage.

The one-time build: 30 documents, 134 chunks. Without caching each chunk rereads the whole document at 103,017 input tokens; with caching each document is written once (17,340), later chunks are cache reads (60,137), plus uncacheable text and instruction (25,540) and output (13,400). At placeholder prices that is about 29% cheaper, and the finer the chunks the higher the ratio.

Per query: once a header is in the store it is read twice on every query — once in reranking and once in the context — raising cost by about 12.3%. And amortizing the one-time cost below a tenth of the per-query cost takes only 217 queries.

So the conclusion is counter-intuitive: the index build is the small money, and the few dozen extra tokens per query are the long-term bill. That ledger also yields an immediately usable optimization: headers go only into the index and not into the context. The model generating an answer does not need that locating line; it is useful only to the retriever. Flipping that one switch on the same index leaves every metric unchanged and fits 36 more tokens into the 600-token budget (500 becoming 536).

Tree-based recursive aggregation: making "roughly what this material covers" retrievable

The three catalogs above all optimize finding that one passage. One class of question is not that shape at all:

How many departments does Skyladder's knowledge base cover in all, and roughly what is each about?

Run it and you see the difficulty: a candidate pool of 20 covers 12 documents while the store has 30. The answer is spread across every document, and no top-k assembles it — it wants a summary of the whole store rather than a few passages.

Tree-based recursive aggregation's idea is that since the summary is not in the corpus, manufacture it and index it. Cluster all chunks by vector and have a model write a summary per cluster; those summaries become a new layer of nodes to cluster and summarize again, recursing to the top. The index then holds both leaf-level original chunks and several layers of summary chunks above: detail questions hit leaves and summary questions hit high-level summaries — one index, two granularities.

The cost is in building: clustering the whole store computes every vector once, and each cluster of each layer costs one model call, with a corpus change forcing recomputation of the affected branches. The criterion is what share of questions are summary-type — under a tenth and do not adopt it yet.

Graph retrieval: strong at multi-hop and global, expensive to build

One evaluation question asks who must approve a production database failover in writing and what that person's name is. The answer spans two documents, one stating it requires the platform team lead's written approval and the other stating who the platform team lead is.

That question fails under all five index structures in exactly the same way: the document with the name never once appears in the 20-candidate pool. The query contains neither the name nor any word literally or semantically close to that document. Chunking, headers, and parent backfill are all irrelevant; it was simply never retrieved.

Graph retrieval targets that gap: extract entities and relations into a graph first, and at retrieval time walk one or two hops along the edges. The second document is not fetched by similarity but walked to along an edge.

Building costs far more than one model call: entities need disambiguating, relations deduplicating, and a document update recomputes the affected subgraph, plus a graph store to maintain (incremental updates on day thirteen). The barrier is not technical but whether you have enough must-cross-entities questions to amortize it.

A glance at multimodal, and which catalog a query actually takes

A knowledge base often also holds charts and screenshots. The least-effort approach is turning them into text before indexing: have a multimodal model write a description per image, index that as a chunk, and keep the image path in the metadata. Retrieval goes through the text path unchanged, and the original image is attached beside the citation afterwards. Separate vector spaces for images and text are more refined and need a model change and an index rebuild, whose benefit must first be proven with day eight's evaluation.

Back to the opening suspense: with three indexes built, which does a query take?

By default, none of them; take the one you already had. All five of today's structures stopped at 93.8% recall and not one beat the baseline; the only thing that moved is nDCG@10 (headers lifting it from 0.6438 to 0.7218), and the summary index fell to 87.5%. That does not mean the techniques are useless; it means each patches one specific shortfall, and without that shortfall your system gains only the cost.

So the order is: look at what your failure cases look like using the evaluation set. Chunks cut apart, adopt parent-child; chunks that alone do not say what they are about with vectors as the main route, adopt contextual retrieval; a high share of summary questions, adopt tree aggregation; a high share of cross-entity chains, adopt graph retrieval. Failure cases first, index structures second.

If you genuinely run several at once, the routing criterion is not which is most accurate but the question's shape — which is what yesterday's intent router does. A misclassification falls back to the default rather than querying all of them in parallel.

Source Reading

Hands-On Lab

Run starter/ as-is and most acceptance items fall short: the header column is identical to the heading path, the summary index's two rows match exactly, and the caching ledger is negative. The five exercise points fix them one at a time, all under MOCK=1 with neither network nor key.

1. Implement parent-child chunking: store heading nodes as parents, cut 200-character children within a section and attach their belonging, and watch table one's chunk count become 158.
2. Implement the contextual header: a rule version offline and a model version online, and watch table two's third column pull away from the second.
3. Add parent backfill and deduplication to context assembly, and watch parent-child's context tokens and recall become normal.
4. Wire up the summary index's two-stage retrieval, watch table three's two rows diverge, and work out why recall falls.
5. Compute the prompt caching ledger, watch table five's saving go from negative to about 29%, then change the placeholder prices once and rerun to see the share flip.

Interview Questions

Today's 4 questions are in the question bank below, weighted toward where each index structure applies, contextual retrieval's cost and benefit, and graph retrieval's adoption threshold. Expand each one and read the analysis before the key points — practicing the derivation beats memorizing bullets.

Checklist and Tomorrow

• Implement parent-child and summary indexes, and explain which category of question each makes answerable
• Land contextual retrieval: add contextual descriptions to each chunk, and work out the one-time cost of building the index
• Explain what problems tree-based recursive aggregation and graph retrieval each solve, and under what conditions their cost isn't worth it
• Explain why headers-only-in-the-index is a free gain
• Name this chapter's two experimental boundaries and which question they make unanswerable
• All 5 acceptance criteria of the lab pass
• Answer at least 3 of the 4 interview questions without looking at the key points

Tomorrow (D12) wraps retrieval as a tool inside an agent loop, letting the model decide whether to search, how many times, and whether to start over. The order is deliberate: today's recurring failure mode is one retrieval not assembling the answer — that approver question failed under all five index structures. What index structures cannot solve can only be solved by searching several times, and that requires somebody to decide what to search and when to stop. That somebody is tomorrow's protagonist.