Retrieval

Retrieval is part of the Query workflow. It embeds a user query with input_type="query", searches the vector database, and returns the closest stored chunks. Use this page to understand the retrieval stage. Use the interface-specific pages when you need exact parameters, flags, request fields, or response shapes.

Retrieval does not generate an answer. It returns chunks and scores. Use Chat when you want answer generation over retrieved context.

Basic retrieval

from ragrails import RagRails

rag = RagRails(
    collection="support",
    vector_store={"provider": "qdrant", "url": "http://localhost:6333"},
    embedding={"provider": "voyage", "model": "voyage-3"},
)

result = rag.retrieve("How do refunds work?", top_k=10)

for chunk in result.items:
    print(chunk.score, chunk.chunk_id, chunk.text)

ragrails retrieve "How do refunds work?"   --vector-db qdrant   --collection support   --url http://localhost:6333   --provider voyage   --model voyage-3   --top-k 10

curl -X POST http://127.0.0.1:8000/v1/retrieve   -H "Content-Type: application/json"   -d '{
    "query": "How do refunds work?",
    "provider": "voyage",
    "model": "voyage-3",
    "vector_db": "qdrant",
    "collection": "support",
    "url": "http://localhost:6333",
    "top_k": 10
  }'

Result:

{
  "query": "How do refunds work?",
  "search_query": "How do refunds work?",
  "retrieved": 2,
  "items": [
    {
      "id": "chunk-1",
      "chunk_id": "chk_refunds",
      "score": 0.84,
      "text": "Refunds are available within 30 days.",
      "metadata": {
        "title": "Refund policy",
        "source": "policy.md"
      },
      "rerank_score": null
    }
  ],
  "failed": 0,
  "errors": []
}

Key	Meaning
`query`	Original user query.
`search_query`	Query actually embedded and searched; differs when query rewriting is enabled.
`retrieved`	Number of vector-store candidates returned before optional rerank trimming.
`items`	Retrieved chunks with text, scores, metadata, and optional rerank scores.
`items[].id`	Stored vector ID. Use this for edit and delete operations.
`items[].chunk_id`	Original chunk ID carried from chunking and storage.
`items[].score`	Vector similarity score from the store.
`items[].rerank_score`	Reranker score when reranking is enabled; otherwise `null`.
`failed`	Number of retrieval-stage failures.
`errors`	Structured validation, query embedding, vector-store, rewrite, or rerank errors.

Query embeddings

Retrieval uses the configured embedding model with input_type="query". This must match the model used during indexing, but not the input type.

# Indexing uses document embeddings.
embedded = rag.embed(chunks=chunks.items, input_type="document")

# Retrieval uses query embeddings automatically.
results = rag.retrieve("refund window", top_k=10)

Use the same embedding provider and model for indexing and retrieval. Document and query vectors from different models are not comparable.

Tuning knobs

Symptom	Adjustment
Too few or too many candidates	Change `top_k`.
Right topic appears but order is weak	Enable reranking.
Follow-up questions miss context	Enable query rewriting with session context.
Wrong knowledge base searched	Check `vector_db`, `collection`, and `url`.

Reranking

Reranking takes vector-search candidates and reorders them with a reranker. Retrieve wide, then rerank down.

result = rag.retrieve(
    "How do refunds work?",
    top_k=20,
    use_rerank=True,
    rerank_top_k=5,
)

ragrails retrieve "How do refunds work?"   --vector-db qdrant   --collection support   --url http://localhost:6333   --provider voyage   --model voyage-3   --top-k 20   --rerank   --reranker voyage   --reranker-model rerank-2-lite   --rerank-top-k 5

curl -X POST http://127.0.0.1:8000/v1/retrieve   -H "Content-Type: application/json"   -d '{
    "query": "How do refunds work?",
    "provider": "voyage",
    "model": "voyage-3",
    "vector_db": "qdrant",
    "collection": "support",
    "url": "http://localhost:6333",
    "top_k": 20,
    "use_rerank": true,
    "reranker": "voyage",
    "reranker_model": "rerank-2-lite",
    "rerank_top_k": 5
  }'

Result:

{
  "query": "How do refunds work?",
  "search_query": "How do refunds work?",
  "retrieved": 20,
  "items": [
    {
      "id": "chunk-1",
      "chunk_id": "chk_refunds",
      "score": 0.77,
      "rerank_score": 0.94,
      "text": "Refunds are available within 30 days.",
      "metadata": {"title": "Refund policy"}
    }
  ],
  "failed": 0,
  "errors": []
}

Start with top_k=20 and rerank_top_k=5. The reranker needs enough candidates to improve ordering.

Query rewriting

Query rewriting turns a follow-up into a standalone search query before embedding. It needs an LLM.

result = rag.retrieve(
    "What about annual plans?",
    use_query_rewrite=True,
    session_context="The user is asking about refund policy.",
)

print(result.search_query)

# The CLI retrieval command does not expose query rewriting flags yet.
ragrails retrieve "What about annual plans?"   --vector-db qdrant   --collection support   --url http://localhost:6333

curl -X POST http://127.0.0.1:8000/v1/retrieve   -H "Content-Type: application/json"   -d '{
    "query": "What about annual plans?",
    "provider": "voyage",
    "model": "voyage-3",
    "vector_db": "qdrant",
    "collection": "support",
    "url": "http://localhost:6333",
    "use_query_rewrite": true,
    "session_context": "The user is asking about refund policy."
  }'

Result:

{
  "query": "What about annual plans?",
  "search_query": "What is the refund policy for annual plans?",
  "retrieved": 1,
  "items": [
    {
      "id": "chunk-annual-refunds",
      "chunk_id": "chk_annual_refunds",
      "score": 0.81,
      "text": "Annual plans are refundable within 30 days.",
      "metadata": {"title": "Refund policy"},
      "rerank_score": null
    }
  ],
  "failed": 0,
  "errors": []
}

The SDK can use a configured LLM for rewriting. REST exposes rewrite flags, but the server still needs a usable LLM provider configured.

Query pipeline

query() is the high-level query helper. It wraps embedding and retrieval settings in stable nested objects and returns the same RetrieveResult shape.

result = rag.query(
    "How do refunds work?",
    embedding={"provider": "voyage", "model": "voyage-3"},
    retrieval={
        "top_k": 20,
        "rerank": {"enabled": True, "top_k": 5},
        "query_rewrite": {
            "enabled": True,
            "session_context": "The user is asking about billing policy.",
        },
    },
)

ragrails query "How do refunds work?"   --vector-db qdrant   --collection support   --url http://localhost:6333   --provider voyage   --model voyage-3   --top-k 20   --rerank   --rerank-top-k 5

curl -X POST http://127.0.0.1:8000/v1/pipelines/query   -H "Content-Type: application/json"   -d '{
    "query": "How do refunds work?",
    "embedding": {"provider": "voyage", "model": "voyage-3"},
    "retrieval": {
      "vector_db": "qdrant",
      "collection": "support",
      "url": "http://localhost:6333",
      "top_k": 20,
      "rerank": {"enabled": true, "top_k": 5},
      "query_rewrite": {
        "enabled": true,
        "session_context": "The user is asking about billing policy."
      }
    }
  }'

The CLI query command supports reranking, but it does not expose query rewrite flags yet. Use SDK or REST for query rewriting in the high-level query pipeline.

Possible errors

Interface validation errors raise immediately in SDK and REST. Core retrieval failures are returned in the result errors list when processing can continue. See Errors for the shared shapes.

{
  "query": "",
  "search_query": "",
  "retrieved": 0,
  "items": [],
  "failed": 1,
  "errors": [
    {
      "source": "",
      "source_kind": "query",
      "stage": "validate",
      "error": "query must be a non-empty string",
      "isRetryable": false,
      "attempts": 1
    }
  ]
}

{
  "query": "How do refunds work?",
  "search_query": "How do refunds work?",
  "retrieved": 0,
  "items": [],
  "failed": 1,
  "errors": [
    {
      "source": "How do refunds work?",
      "source_kind": "query",
      "stage": "retrieve",
      "error": "Collection not found: support",
      "isRetryable": true,
      "attempts": 1
    }
  ]
}

{
  "query": "How do refunds work?",
  "search_query": "How do refunds work?",
  "retrieved": 10,
  "items": [],
  "failed": 10,
  "errors": [
    {
      "source": "How do refunds work?",
      "source_kind": "query",
      "stage": "rerank",
      "error": "reranker returned a different number of scores than input results",
      "isRetryable": true,
      "attempts": 1
    }
  ]
}

Next steps

Use Chat to generate grounded answers from retrieved chunks.
Use Pipeline Overview to see how retrieval fits into the full RAG flow.
Use Vector Databases to verify provider names and collection settings.

Get Started

Features

Capabilities

Use Cases

Walkthroughs

Basic retrieval

Query embeddings

Tuning knobs

Reranking

Query rewriting

Query pipeline

Possible errors

Next steps

​Basic retrieval

​Query embeddings

​Tuning knobs

​Reranking

​Query rewriting

​Query pipeline

​Possible errors

​Next steps

Basic retrieval

Query embeddings

Tuning knobs

Reranking

Query rewriting

Query pipeline

Possible errors

Next steps