---
title: Concepts
description: The building blocks of Retrieval SDK — documents, hits, retrievers, indexes, embedders, stores and rerankers — and how they fit together.
sidebar:
  order: 2
---

## 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:

```txt
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.
