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
topKhits. - Scores are only comparable within one result list. That is why
hybridfuses ranks, not scores.