Skip to content
Retrieval SDK
Esc
↑↓navigate↵open⌘Jpreview
On this page

Concepts

The building blocks of Retrieval SDK — documents, hits, retrievers, indexes, embedders, stores and rerankers — and how they fit together.

Data

  • Document: { id, text, metadata? }. What you search.
  • Hit: { id, score }. One result. A higher score is always better.

Contracts

Everything is a small interface, so you can swap any piece.

Contract Does Built in
Retriever Turns a query into ranked hits. All of the below
Index A Retriever you can add and remove documents in. bm25, vectorSearch, Elasticsearch
Embedder Turns texts into vectors. AI SDK, Cohere
VectorStore Stores vectors and finds the closest ones. Memory, pgvector, Qdrant
DocumentStore Gets documents by id, so a reranker can read their text. Memory
Reranker Reorders texts by how well they answer the query. AI SDK, Cohere

How they fit

Every search step is a Retriever, so they nest:

withRerank ─ reranks the top candidates
└─ hybrid ─ merges rankings with RRF
   ├─ bm25 ─ matches keywords
   └─ vectorSearch ─ matches meaning (Embedder + VectorStore)

Use one layer or all of them. evaluate takes any Retriever, so you can measure each layer and keep only what helps.

Rules every retriever follows

  • Hits are sorted by score, highest first.
  • Ids are unique.
  • At most topK hits.
  • Scores are only comparable within one result list. That is why hybrid fuses ranks, not scores.

Was this page helpful?