Retrievers

Purpose and Scope

Retrievers are the part of a LlamaIndex application that decide which stored context should be considered for a user request. In a RAG system, generation is only as useful as the context supplied to the model, so the retriever sits between indexed data and downstream response construction. The official API reference presents BaseRetriever as the central interface and also exposes BaseImageRetriever for image-oriented retrieval. Query engines then build on retrievers: a RetrieverQueryEngine turns retrieved context into an answer, while a router query engine can choose among retrieval-backed routes for more complex applications.

This page focuses on the retriever API family visible in the repository documentation. The selected source files are API reference entry points for several concrete retriever implementations: an auto-merging retriever in core, lexical BM25 retrieval, Bedrock knowledge base retrieval, DuckDB retrieval, Galaxia retrieval, and an Alletra X10000 retriever integration. Together they show the intended extension pattern: applications program to a retriever contract, while individual packages provide retrieval strategies for different data stores, scoring methods, or hosted services. Sources: docs/api_reference/api_reference/retrievers/auto_merging.md, docs/api_reference/api_reference/retrievers/bm25.md, docs/api_reference/api_reference/retrievers/bedrock.md

Relevant Source Files

• docs/api_reference/api_reference/retrievers/auto_merging.md documents the AutoMergingRetriever member from llama_index.core.retrievers, making it the source-backed core retriever entry on this page.
• docs/api_reference/api_reference/retrievers/bm25.md documents BM25Retriever from llama_index.retrievers.bm25, representing keyword and lexical retrieval as an integration-style retriever.
• docs/api_reference/api_reference/retrievers/bedrock.md documents AmazonKnowledgeBasesRetriever from llama_index.retrievers.bedrock, showing that retrievers can wrap a managed external knowledge-base service.
• docs/api_reference/api_reference/retrievers/duckdb_retriever.md documents DuckDBRetriever from llama_index.retrievers.duckdb_retriever, showing a database-backed retrieval implementation.
• docs/api_reference/api_reference/retrievers/galaxia.md documents GalaxiaRetriever from llama_index.retrievers.galaxia, identifying another provider-specific retriever surface.
• docs/api_reference/api_reference/retrievers/alletra_x10000_retriever.md documents AlletraX10000Retriever from llama_index.retrievers.alletra_x10000_retriever, showing a storage-system-specific retriever integration.

The important thing to notice is that these files are not tutorials; they are generated API-reference anchors. Their value is in the exact public names and modules they expose. When you are deciding how to assemble an application, use the conceptual retriever contract first, then select an implementation whose package, service, or retrieval algorithm matches your data location and ranking requirements. The same query-engine layer can remain stable while the underlying retriever changes, which is why these implementations are documented as members of a shared retriever family. Sources: docs/api_reference/api_reference/retrievers/alletra_x10000_retriever.md, docs/api_reference/api_reference/retrievers/duckdb_retriever.md, docs/api_reference/api_reference/retrievers/galaxia.md

Core Contract and Runtime Role

A retriever accepts a query-like input and returns relevant units of context for later processing. In LlamaIndex terminology, those units are typically nodes created from documents during loading, parsing, and indexing. A retriever is therefore not the same as an index and not the same as a response synthesizer. The index organizes or persists data, the retriever selects candidate context, and the query engine or chat engine coordinates retrieval with synthesis, memory, prompts, and model calls. Keeping these roles separate lets you tune recall and precision without rewriting the rest of the application.

The API-reference snippets show both framework-level and integration-level retrievers. AutoMergingRetriever lives under llama_index.core.retrievers, so it belongs to the core retrieval layer rather than a single external provider. Its name indicates a retrieval strategy that can merge retrieved context, which is useful when chunking has split source material into smaller pieces but answers require a broader surrounding unit. By contrast, BM25Retriever, DuckDBRetriever, AmazonKnowledgeBasesRetriever, GalaxiaRetriever, and AlletraX10000Retriever are exposed from llama_index.retrievers.* modules, signaling separately packaged or provider-oriented implementations. Sources: docs/api_reference/api_reference/retrievers/auto_merging.md, docs/api_reference/api_reference/retrievers/bm25.md

In practice, the retriever is the component you change when the question is about recall behavior. If answers are grounded in the wrong passages, if lexical matching should be preferred over vector similarity, or if data already lives in a managed knowledge base, the retriever layer is the natural place to make that decision. Query engines consume retriever output through a stable interface, so an application can start with a simple retriever and later move to a managed service, database-backed retriever, or hierarchical retrieval strategy without changing the user-facing query flow.

System-to-Code Mapping

Public retriever	API reference module	What it represents	Source
AutoMergingRetriever	llama_index.core.retrievers	Core retriever that belongs to the framework retrieval family	docs/api_reference/api_reference/retrievers/auto_merging.md
BM25Retriever	llama_index.retrievers.bm25	Lexical retrieval based on the BM25 retriever integration surface	docs/api_reference/api_reference/retrievers/bm25.md
AmazonKnowledgeBasesRetriever	llama_index.retrievers.bedrock	Retriever for Amazon Bedrock knowledge bases	docs/api_reference/api_reference/retrievers/bedrock.md
DuckDBRetriever	llama_index.retrievers.duckdb_retriever	Retriever backed by DuckDB-oriented storage or queries	docs/api_reference/api_reference/retrievers/duckdb_retriever.md
GalaxiaRetriever	llama_index.retrievers.galaxia	Provider-specific retriever integration	docs/api_reference/api_reference/retrievers/galaxia.md
AlletraX10000Retriever	llama_index.retrievers.alletra_x10000_retriever	Storage-system-specific retriever integration	docs/api_reference/api_reference/retrievers/alletra_x10000_retriever.md

This mapping should be read as an API entry-point map, not as an exhaustive behavior specification. The repository pages identify the public classes and modules that the generated documentation will expand from the installed packages. For a developer, that means the first design decision is not which import path is longest, but which retrieval boundary you want. Core retrievers are usually chosen for framework-native behavior; integration retrievers are chosen when the retrieval system is already an external product, database, or specialized ranking implementation. Sources: docs/api_reference/api_reference/retrievers/bedrock.md, docs/api_reference/api_reference/retrievers/duckdb_retriever.md, docs/api_reference/api_reference/retrievers/galaxia.md

Execution Flow in a RAG Pipeline

A typical retrieval-centered flow begins before the retriever is called. Data is loaded into documents, parsed into nodes, indexed, and optionally persisted. At query time, the retriever receives the user request or a transformed query and selects nodes or records that appear relevant. The query engine then packages that retrieved context for response synthesis, where an LLM produces the final answer. If the application is conversational, a chat engine can add chat history and state, but retrieval still performs the same essential job: selecting evidence for the model.

Different retriever implementations enter this flow at different points. A BM25 retriever is attractive when exact terms, identifiers, or keyword overlap are important. A database retriever such as the DuckDB entry point is useful when tabular or SQL-adjacent data access is part of the retrieval story. A Bedrock knowledge-base retriever is appropriate when the application delegates retrieval to Amazon Bedrock rather than maintaining all retrieval infrastructure locally. Provider-specific retrievers such as Galaxia and Alletra X10000 follow the same pattern: they let the LlamaIndex application call into an external retrieval capability through a retriever-shaped API. Sources: docs/api_reference/api_reference/retrievers/bm25.md, docs/api_reference/api_reference/retrievers/duckdb_retriever.md, docs/api_reference/api_reference/retrievers/bedrock.md

Because query engines and router query engines can sit above retrievers, retriever choice also affects composition. A simple application may have one retriever and one query engine. A broader application may expose multiple tools or routes, each backed by a different retriever optimized for a particular corpus or service. The retriever contract is what makes those combinations practical: the routing layer can decide where a question should go, and each route can use the retrieval implementation that best matches its data source and ranking model.

API Components Reference

The public components visible in the selected API reference pages are concise but important. AutoMergingRetriever is the named core retriever from llama_index.core.retrievers. BM25Retriever is exported from the BM25 retriever module. AmazonKnowledgeBasesRetriever is exported from the Bedrock retriever module. DuckDBRetriever, GalaxiaRetriever, and AlletraX10000Retriever are each documented as members of their respective retriever modules. Those names are the stable starting points to use when moving from conceptual design to package-specific API documentation. Sources: docs/api_reference/api_reference/retrievers/auto_merging.md, docs/api_reference/api_reference/retrievers/alletra_x10000_retriever.md

Name	Import namespace shown by docs	Selection signal
AutoMergingRetriever	llama_index.core.retrievers	Use when you want framework-native retrieval that can consolidate retrieved context.
BM25Retriever	llama_index.retrievers.bm25	Use when lexical matching is the desired retrieval strategy.
AmazonKnowledgeBasesRetriever	llama_index.retrievers.bedrock	Use when retrieval should come from Amazon Bedrock Knowledge Bases.
DuckDBRetriever	llama_index.retrievers.duckdb_retriever	Use when DuckDB-backed querying is part of retrieval.
GalaxiaRetriever	llama_index.retrievers.galaxia	Use when integrating with Galaxia-specific retrieval.
AlletraX10000Retriever	llama_index.retrievers.alletra_x10000_retriever	Use when integrating with the Alletra X10000 retriever package.

Implementation Guidance and Next Steps

When implementing retrieval in an application, start by naming the user experience you need: semantic search over chunks, keyword search over identifiers, retrieval from a managed knowledge base, or retrieval from a database or storage system. Then choose the retriever implementation that fits that boundary and wrap it in a query engine when you need answer generation. This keeps retrieval testing focused: inspect retrieved nodes or records first, then evaluate synthesis separately. If generated answers are poor, you can determine whether the failure came from missing context, bad ranking, or response construction.

Next, read the pages that surround this one in the architecture. The Indexes page explains how data becomes searchable. The Query Engines page explains how retrievers are used to produce answers. The Response Synthesis page explains how retrieved context is turned into final text. If you are choosing a hosted or external retriever, also review the relevant integration family pages so installation, credentials, service limits, and persistence are treated as part of the design rather than as afterthoughts.