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

# Improve retrieval quality

> Improve RAG retrieval quality in LangChain with metadata filtering, query transformation, hybrid search, maximal marginal relevance, and reranking.

Retrieval quality sets the ceiling for a [RAG](https://docs.langchain.com/oss/javascript/deepagents/retrieval.md) application: a model can only answer from the context it receives. When answers are incomplete or wrong, the retriever is often the cause, not the model. This guide covers techniques to improve what your retriever returns, from cheap configuration changes to a two-stage reranking pipeline.

Each technique changes the body of the baseline retrieval tool below. Combine them as needed, and measure every change against a fixed dataset so you keep what helps.

> [!TIP]
>
> Use [LangSmith](https://smith.langchain.com?utm_source=docs\&utm_medium=cta\&utm_campaign=langsmith-signup\&utm_content=oss-langchain-retrieval-optimization) to score those experiments. The [RAG evaluation tutorial](https://docs.langchain.com/langsmith/evaluate-rag-tutorial.md) shows how to measure retrieval and answer quality.

## Before you begin

This guide assumes you have an indexed `vector_store` and expose retrieval to an agent as a [tool](https://docs.langchain.com/oss/javascript/langchain/tools.md). For indexing, see [Build a semantic search engine](https://docs.langchain.com/oss/javascript/langchain/knowledge-base.md).

The baseline retrieval tool runs a single similarity search:

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import * as z from "zod";
import { tool } from "@langchain/core/tools";

const retrieve = tool(
  async ({ query }) => {
    const docs = await vectorStore.similaritySearch(query, 4);
    const serialized = docs
      .map((doc) => `Source: ${doc.metadata.source}\nContent: ${doc.pageContent}`)
      .join("\n\n");
    return [serialized, docs];
  },
  {
    name: "retrieve",
    description: "Retrieve information related to a query.",
    schema: z.object({ query: z.string() }),
    responseFormat: "content_and_artifact",
  },
);
```

Pass the tool to an agent with [createAgent](https://reference.langchain.com/javascript/langchain/index/createAgent):

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { createAgent } from "langchain";

const agent = createAgent({ model: "claude-sonnet-4-6", tools: [retrieve] });
```

## Choose a technique

Start with the technique that matches the failure you observe, then layer others as needed. Reranking gives the largest gain for most applications and composes well with a broad first-stage retrieval.

| Symptom | Technique |
| - | - |
| Results come from the wrong subset (wrong tenant, date, or category) | [Filter by metadata](#filter-by-metadata) |
| Relevant documents are missed when phrased differently than the question | [Transform the query](#transform-the-query) |
| Exact names, codes, or rare keywords are missed | [Combine semantic and keyword search](#combine-semantic-and-keyword-search) |
| Several near-duplicate chunks crowd out other information | [Diversify results with maximal marginal relevance](#diversify-results-with-maximal-marginal-relevance) |
| Results are roughly relevant but poorly ordered | [Rerank retrieved documents](#rerank-retrieved-documents) |

A common high-quality pipeline combines several: filter to the right scope, retrieve a broad candidate set with hybrid search, then rerank to a small set. Validate the combination on a dataset with [LangSmith evaluation](https://docs.langchain.com/langsmith/evaluate-rag-tutorial.md) before shipping.

The sections below change the body of the baseline tool. Each is independent, so adopt only the ones that address a problem you observe.

## Filter by metadata

Metadata filtering restricts the search to a subset of documents before similarity search runs. It improves precision and reduces latency by shrinking the candidate set, and it is the most reliable way to scope retrieval to a tenant, a date range, a category, or a section.

Filtering requires that you attach metadata to each chunk at indexing time. Apply a static filter when the scope is fixed:

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const docs = await vectorStore.similaritySearch(query, 4, {
  section: "introduction",  // [!code highlight]
});
```

To let the model choose the scope, expose the filter as a tool argument. The model populates it from the conversation:

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import * as z from "zod";
import { tool } from "@langchain/core/tools";

const retrieve = tool(
  async ({ query, section }) => {
    const docs = await vectorStore.similaritySearch(query, 4, { section });
    const serialized = docs
      .map((doc) => `Source: ${doc.metadata.source}\nContent: ${doc.pageContent}`)
      .join("\n\n");
    return [serialized, docs];
  },
  {
    name: "retrieve",
    description: "Retrieve information from a specific section of the document.",
    schema: z.object({
      query: z.string(),
      section: z.enum(["introduction", "methods", "results"]),
    }),
    responseFormat: "content_and_artifact",
  },
);
```

> [!NOTE]
>
> Filter syntax is vector-store specific. The dictionary form shown here works with most production stores, such as Pinecone and PGVector. Some stores, including `InMemoryVectorStore`, take a predicate function instead. See your [vector store integration](https://docs.langchain.com/oss/javascript/integrations/vectorstores.md) for details.

## Transform the query

A user question is not always a good search query. It can be vague, conversational, or contain several distinct information needs. Transforming the question into one or more focused queries before retrieval improves recall.

Generate focused queries with [structured output](https://docs.langchain.com/oss/javascript/langchain/structured-output.md), run a search for each, then merge the results:

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import * as z from "zod";
import { ChatAnthropic } from "@langchain/anthropic";

const SearchQueries = z.object({
  queries: z.array(z.string()).describe("One to three search queries."),
});

const queryModel = new ChatAnthropic({ model: "claude-sonnet-4-6" }).withStructuredOutput(
  SearchQueries,
);

async function expandQuery(question: string): Promise<string[]> {
  const result = await queryModel.invoke(
    `Generate one to three focused search queries for: ${question}`,
  );
  return result.queries;
}
```

Retrieve for each generated query and deduplicate the results:

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { tool } from "@langchain/core/tools";

const retrieve = tool(
  async ({ query }) => {
    const seen = new Set<string>();
    const docs = [];
    for (const expanded of await expandQuery(query)) {
      for (const doc of await vectorStore.similaritySearch(expanded, 4)) {
        if (!seen.has(doc.pageContent)) {
          seen.add(doc.pageContent);
          docs.push(doc);
        }
      }
    }
    const serialized = docs
      .map((doc) => `Source: ${doc.metadata.source}\nContent: ${doc.pageContent}`)
      .join("\n\n");
    return [serialized, docs];
  },
  {
    name: "retrieve",
    description: "Retrieve information related to a query.",
    schema: z.object({ query: z.string() }),
    responseFormat: "content_and_artifact",
  },
);
```

> [!TIP]
>
> An agent already rewrites queries to some degree: it decides what to search for based on the conversation. Query transformation is most useful when you retrieve once per turn, as in a two-step RAG chain, or when a single search misses relevant documents.

## Combine semantic and keyword search

Semantic (dense) search matches meaning, but it can miss exact product codes, identifiers, names, and rare keywords. Keyword (sparse) search matches those terms exactly. Hybrid search runs both and combines the rankings, which improves recall for queries that mix concepts with specific terms.

> [!NOTE]
>
> Many vector store integrations support hybrid search natively, which is the most efficient option for large corpora. See your [vector store integration](https://docs.langchain.com/oss/javascript/integrations/vectorstores.md) to enable it, then request hybrid results inside your retrieval tool.

There is no first-party BM25 retriever. Prefer native hybrid search on your [vector store](https://docs.langchain.com/oss/javascript/integrations/vectorstores.md) when available. For a portable fallback, run a keyword search over the same `chunks` used to build the store (the example uses simple term overlap; replace it with your store's keyword API or a BM25 library), then merge rankings with reciprocal rank fusion:

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import * as z from "zod";
import type { Document } from "@langchain/core/documents";
import { tool } from "@langchain/core/tools";

function keywordSearch(query: string, k = 10): Document[] {
  const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
  return chunks
    .map((doc) => ({
      doc,
      score: terms.reduce(
        (acc, term) => acc + (doc.pageContent.toLowerCase().includes(term) ? 1 : 0),
        0,
      ),
    }))
    .filter(({ score }) => score > 0)
    .sort((a, b) => b.score - a.score)
    .slice(0, k)
    .map(({ doc }) => doc);
}

function reciprocalRankFusion(resultLists: Document[][], smoothing = 60): Document[] {
  const scores = new Map<string, number>();
  const docsByKey = new Map<string, Document>();
  for (const docs of resultLists) {
    docs.forEach((doc, rank) => {
      const key = doc.pageContent;
      docsByKey.set(key, doc);
      scores.set(key, (scores.get(key) ?? 0) + 1 / (smoothing + rank));
    });
  }
  return [...scores.entries()]
    .sort((a, b) => b[1] - a[1])
    .map(([key]) => docsByKey.get(key)!);
}

const retrieve = tool(
  async ({ query }) => {
    const dense = await vectorStore.similaritySearch(query, 10);
    const sparse = keywordSearch(query, 10);
    const docs = reciprocalRankFusion([dense, sparse]).slice(0, 4);
    const serialized = docs
      .map((doc) => `Source: ${doc.metadata.source}\nContent: ${doc.pageContent}`)
      .join("\n\n");
    return [serialized, docs];
  },
  {
    name: "retrieve",
    description: "Retrieve information related to a query.",
    schema: z.object({ query: z.string() }),
    responseFormat: "content_and_artifact",
  },
);
```

## Diversify results with maximal marginal relevance

Plain similarity search can return several near-duplicate chunks, which wastes context on repeated information. Maximal marginal relevance (MMR) selects results that are both relevant to the query and diverse from one another.

Use the vector store's maximal marginal relevance search in place of `similarity_search`:

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const docs = await vectorStore.maxMarginalRelevanceSearch(query, {
  k: 4, // number of documents to return
  fetchK: 20, // number of candidates to consider before selecting
  lambda: 0.5, // 1.0 favors relevance, 0.0 favors diversity
});
```

MMR fetches `fetch_k` candidates by similarity, then selects `k` that balance relevance against redundancy. Not all vector stores implement MMR; check your [vector store integration](https://docs.langchain.com/oss/javascript/integrations/vectorstores.md).

## Rerank retrieved documents

Embedding similarity is a coarse relevance signal, so the top result by similarity is not always the most relevant. A reranker scores each candidate against the query directly and reorders them, which usually produces the largest single quality gain. Use two-stage retrieval: fetch a broad candidate set with similarity search, then rerank down to a small, high-precision set.

Call a reranker inside the tool. This example uses `CohereRerank` from `@langchain/cohere`:

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { tool } from "@langchain/core/tools";
import { CohereRerank } from "@langchain/cohere";

const reranker = new CohereRerank({ model: "rerank-v5.0-pro", topN: 4 });

const retrieve = tool(
  async ({ query }) => {
    const candidates = await vectorStore.similaritySearch(query, 20);
    const docs = await reranker.compressDocuments(candidates, query);
    const serialized = docs
      .map((doc) => `Source: ${doc.metadata.source}\nContent: ${doc.pageContent}`)
      .join("\n\n");
    return [serialized, docs];
  },
  {
    name: "retrieve",
    description: "Retrieve information related to a query.",
    schema: z.object({ query: z.string() }),
    responseFormat: "content_and_artifact",
  },
);
```

> [!NOTE]
>
> Reranking adds an extra step, and hosted rerankers add an API call per retrieval, which increases latency. In most RAG applications the quality gain is worth the cost. See the [Cohere reranker integration](https://docs.langchain.com/oss/javascript/integrations/document_compressors/cohere_rerank) for setup, or your [retriever integration](https://docs.langchain.com/oss/javascript/integrations/retrievers.md) for other options.

## See also

* [Retrieval](https://docs.langchain.com/oss/javascript/deepagents/retrieval.md): concepts and RAG architectures
* [Build a semantic search engine](https://docs.langchain.com/oss/javascript/langchain/knowledge-base.md): index documents into a vector store
* [RAG with Deep Agents](https://docs.langchain.com/oss/javascript/deepagents/rag.md): end-to-end retrieval and generation with Deep Agents
* [Build a custom RAG agent with LangGraph](https://docs.langchain.com/oss/javascript/langgraph/agentic-rag.md): grade documents and rewrite queries with a custom graph
* [Evaluate a RAG application](https://docs.langchain.com/langsmith/evaluate-rag-tutorial.md): measure retrieval and answer quality
* [Retriever integrations](https://docs.langchain.com/oss/javascript/integrations/retrievers.md) and [vector store integrations](https://docs.langchain.com/oss/javascript/integrations/vectorstores.md)

***

[Connect these docs](https://docs.langchain.com/use-these-docs.md) to your agent of choice via MCP for real-time answers.

[Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/oss/langchain/retrieval-optimization.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
