> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ragrails.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieval

> Retrieve, rerank, and rewrite queries with the SDK.

Retrieval embeds a user query, searches the vector database, and returns the closest chunks. Use `rag.query()` for the workflow-level API and `rag.retrieve()` when you want direct control over retrieval objects.

```python theme={null}
from ragrails import RagRails

rag = RagRails(
    collection="support",
    vector_store={"provider": "qdrant", "url": "http://localhost:6333"},
    embedding={"provider": "voyage", "model": "voyage-3"},
    llm={"provider": "openai", "model": "gpt-4o-mini"},
    reranker={"provider": "voyage", "model": "rerank-2-lite"},
)
```

## Workflow Retrieval: `query()`

```python theme={null}
result = rag.query("How long do refunds take?", retrieval={"top_k": 5})
```

`query()` returns `query`, `search_query`, `retrieved`, `items`, `failed`, and `errors`.

## Direct Retrieval: `retrieve()`

```python theme={null}
result = rag.retrieve("How long do refunds take?", top_k=5)

for item in result.items:
    print(item.score, item.text)
```

Each retrieved item has `id`, `chunk_id`, `score`, `text`, `metadata`, and optional `rerank_score`.

## Reranking

Retrieve more candidates than you show, then rerank down to the best few.

```python theme={null}
result = rag.retrieve(
    "How long do refunds take?",
    top_k=20,
    use_rerank=True,
    rerank_top_k=5,
)
```

Or use the workflow config shape:

```python theme={null}
result = rag.query(
    "How long do refunds take?",
    retrieval={"top_k": 20, "rerank": {"enabled": True, "top_k": 5}},
)
```

## Query Rewriting

Query rewriting turns follow-up questions into standalone search queries. It requires an LLM.

```python theme={null}
result = rag.retrieve(
    "What about the second step?",
    use_query_rewrite=True,
    session_context="The user is asking about refund setup.",
)

print(result.search_query)
```

Workflow config:

```python theme={null}
result = rag.query(
    "What about the second step?",
    retrieval={"query_rewrite": {"enabled": True, "session_context": "Refund policy thread"}},
)
```

## Parameters

| Parameter                             | Default                              | Description                          |
| ------------------------------------- | ------------------------------------ | ------------------------------------ |
| `query`                               | required                             | Non-empty search query.              |
| `embedder`                            | auto-created                         | Query embedder.                      |
| `vector_db`                           | constructor default, else `"qdrant"` | Vector DB provider.                  |
| `collection`                          | constructor default                  | Collection, index, or class name.    |
| `url`                                 | constructor default                  | Vector DB URL.                       |
| `options`                             | `None`                               | Provider-specific vector DB options. |
| `top_k`                               | `10`                                 | Candidates to retrieve.              |
| `use_query_rewrite`                   | `False`                              | Rewrite query before search.         |
| `rewrite_llm`                         | constructor LLM                      | LLM used for rewriting.              |
| `rewrite_context` / `session_context` | `""`                                 | Context hints for rewriting.         |
| `use_rerank`                          | `False`                              | Rerank results after retrieval.      |
| `reranker`                            | constructor reranker                 | Explicit reranker object.            |
| `rerank_top_k`                        | `5`                                  | Results kept after reranking.        |

<CardGroup cols={2}>
  <Card title="Query" icon="search-check" href="/usage/sdk/query">Use retrieval in the query workflow.</Card>
  <Card title="Chat" icon="messages-square" href="/usage/sdk/chat">Generate answers from retrieved context.</Card>
</CardGroup>