105 Vespa | Document Store

Imagine you’re building a search engine for millions of documents.

A user types:

“vespa architecture”

Within milliseconds, the search engine finds matching documents, ranks them, and returns results.

But here’s the mystery:

Where did the title, description, URL, and body of those results actually come from?

The inverted index only knows which documents contain the words vespa and architecture. It doesn’t store complete documents.

The ranking engine only computes scores. It doesn’t hold the article content either.

The attribute store keeps fast-access values for filtering and sorting. Still not the full document.

So where is the actual article?

The Hidden Warehouse Behind Search

Think of Vespa’s Proton engine as a giant library with three specialized departments.

Department 1: The Detective

The Inverted Index is the detective.

It knows:

vespa → Doc12, Doc45, Doc89
architecture → Doc12, Doc89

Ask it:

“Who contains the word vespa?”

And it instantly answers.

But if you ask:

“Show me the title of Doc12”

It shrugs.It never stored that.

Department 2: The Speed Expert

The Attribute Store is the speed expert. It keeps selected fields in memory:

Doc12:
  price = 499
  rating = 4.8
  category = "books"

Perfect for:

• Filtering
• Sorting
• Grouping
• Ranking features

But again…

• No full article.
• No long description.
• No document body.

Department 3: The Warehouse

Finally, at the back of the building sits a giant warehouse. This is the Document Store. It quietly stores the original documents.

{
  "id": "doc12",
  "title": "Best Vespa Guide",
  "description": "Learn Vespa search architecture",
  "url": "example.com/vespa",
  "body": "Long article..."
}

• Nobody visits this warehouse during matching.
• Nobody visits it during filtering.
• Nobody visits it during ranking.

It only becomes important when Vespa already knows:

“These are the winners.”

Why Not Keep Everything in Memory?

Suppose you have:

100 million documents
5 KB each

That’s roughly:

500 GB

Keeping all of that in RAM would be extremely expensive. Most searches never need most documents.

A query might:

Start with 10 million candidates
↓
Match 10,000
↓
Rank 100
↓
Return 10

Only 10 documents are actually shown to the user. Why load all 100 million into memory?

Instead Vespa keeps:

Fast structures in memory
Large document contents on disk

This separation is one of the reasons Vespa scales efficiently.

What Happens During a Search?

Let’s follow a real query.

Step 1: Find Matches

User searches:

vespa architecture

The inverted index checks its posting lists:

vespa → [12,45,89]
architecture → [12,89]

Result:

Matching Docs:
[12,89]

Step 2: Rank Them

The ranking engine evaluates:

Doc12 = 0.95
Doc89 = 0.91

Top documents selected:

[12,89]

At this point Vespa still hasn’t read the full documents.

Step 3: Visit the Warehouse

Only now does Vespa open the Document Store.

It fetches:

Doc12
Doc89

And loads requested summary fields:

{
  "title": "...",
  "description": "...",
  "url": "..."
}

Notice something important:

Vespa usually doesn’t fetch the entire document body. It retrieves only the fields requested in the result. This keeps retrieval fast.

Step 4: Return Results

Now Vespa finally sends:

[
  {
    "title": "Best Vespa Guide",
    "description": "Learn Vespa search architecture"
  },
  {
    "title": "Search at Scale",
    "description": "Building large search systems"
  }
]

Back to the user.

Where Does It Live Inside Proton?

Inside a content node, Proton roughly looks like:

                 Proton
                   │
      ┌────────────┼────────────┐
      │            │            │
      ▼            ▼            ▼
  Inverted      Attribute     Document
   Index          Store        Store
 term→docs    doc→values    doc→content

Each component has a different job.

This separation is a key Vespa design principle.

Why Compression Matters

The Document Store is usually compressed.

Without compression:

100M docs × 5 KB
≈ 500 GB

With compression:

≈ 150–250 GB

Benefits:

• Less disk usage
• Better cache efficiency
• Faster disk reads
• Lower infrastructure cost

Since documents are mostly read after ranking, compression gives large savings with minimal impact.

The Mental Model

Whenever you think about Vespa queries, imagine three workers:

Worker 1:
"Which documents match?"
      ↓
Inverted Index

Worker 2:
"Which documents are best?"
      ↓
Attribute Store + Ranking

Worker 3:
"Show me the actual content."
      ↓
Document Store

The Document Store is not part of finding documents. It is not part of ranking documents.

Document Store is the final retrieval layer that opens the warehouse only after Vespa already knows exactly which documents the user will see.

That’s why Vespa can search through hundreds of millions of documents quickly while keeping storage costs under control.

Hawkeye View Summary