Query Engines

Purpose and Scope

A query engine is the LlamaIndex interface for asking a natural-language question over data and receiving a rich response rather than raw retrieved records. In a typical retrieval-augmented generation application, the query engine sits at the boundary between user intent and the RAG pipeline: it accepts the question, relies on retrieval or other internal modules to collect relevant context, and returns an answer object suitable for application code. The deployment guide defines the query engine as a generic interface and emphasizes that it is most often built on one or many indexes via retrievers, while still allowing composition for more advanced behavior.

Sources: docs/src/content/docs/framework/module_guides/deploying/query_engine/index.mdx

Use this page when you need to decide where query engines fit relative to indexes, retrievers, chat engines, and specialized query-time modules. An index organizes data for later access; a retriever selects candidate nodes or records; a query engine turns the single user question into an end-to-end query operation. This makes query engines the simplest deployment-facing abstraction for one-shot question answering. If the user experience requires multi-turn conversation, stored conversational state, or back-and-forth interaction, the official deployment guide points readers toward chat engines instead of treating query engines as chat state managers.

Sources: docs/src/content/docs/framework/module_guides/deploying/query_engine/index.mdx

Relevant Source Files

• docs/api_reference/api_reference/query_engine/index.md — anchors the generated API reference page for the query engine entry point, specifically the core base query engine module.
• docs/src/content/docs/framework/module_guides/deploying/query_engine/index.mdx — defines the deployment-facing query engine concept, basic usage pattern, streaming pattern, and links to module and supporting-module guides.
• llama-index-core/llama_index/core/query_engine/flare/schema.py — defines the small FLARE query task schema used by an advanced query engine implementation to track a query string and text span offsets.

The repository separates two kinds of documentation evidence for query engines. The module guide is task-oriented: it explains what a query engine does, when to use it, and the first code path most users should run. The API reference page is intentionally terse in source form because it delegates rendered content to the documented Python object llama_index.core.base.base_query_engine. Together, these files show the intended documentation model: users start from index.as_query_engine() in guides, then consult the base query engine API reference when implementing or integrating against the common query interface.

Sources: docs/api_reference/api_reference/query_engine/index.md, docs/src/content/docs/framework/module_guides/deploying/query_engine/index.mdx

Core Query Flow

The minimal query flow begins with an existing index. Calling index.as_query_engine() creates a query engine configured from that index, and calling query_engine.query(...) runs a natural-language question through the engine. The deployment guide’s starter example intentionally hides lower-level details so users can focus on the interface boundary: the application asks a question, and the query engine returns a response. That is the central contract to preserve when refactoring RAG applications. Components such as retrieval, prompt construction, postprocessing, and synthesis may change internally, but callers can keep depending on a query method at the deployment layer.

Sources: docs/src/content/docs/framework/module_guides/deploying/query_engine/index.mdx

query_engine = index.as_query_engine()
response = query_engine.query("Who is Paul Graham.")

The same guide also documents streaming as an option of the query engine creation step rather than a separate top-level interface. Passing streaming=True to index.as_query_engine(...) changes the response behavior so the caller can consume incremental output from the query execution. This is useful for user interfaces where latency perception matters: the application can start displaying answer tokens or chunks while the full response is still being produced. In the documented pattern, the returned streaming response exposes print_response_stream(), which is a convenience for direct console output and a signal that applications may handle streaming responses differently from regular responses.

Sources: docs/src/content/docs/framework/module_guides/deploying/query_engine/index.mdx

query_engine = index.as_query_engine(streaming=True)
streaming_response = query_engine.query("Who is Paul Graham.")
streaming_response.print_response_stream()

System-to-Code Mapping

At the conceptual level, a query engine has three important relationships. First, it is usually built from indexes, so index construction and persistence happen before query deployment. Second, it commonly depends on retrievers, which are responsible for locating relevant pieces of indexed data. Third, it can be composed with other query engines, which lets an application route or combine questions across multiple data collections, retrieval strategies, or domain-specific engines. The deployment guide states this composition capability directly, so query engines should be treated as building blocks rather than only as final endpoints.

Sources: docs/src/content/docs/framework/module_guides/deploying/query_engine/index.mdx

This mapping is also a practical design checklist. If an application only needs to answer a single question against one data source, start with the index-produced query engine. If it needs different retrieval behavior, configure or replace the retriever behind that engine rather than changing all callers. If it needs to ask across multiple domains, compose query engines and keep each engine responsible for its own data and retrieval rules. If it needs conversational memory or chat history, move up to the chat engine abstraction rather than forcing statefulness into a one-shot query interface.

Sources: docs/src/content/docs/framework/module_guides/deploying/query_engine/index.mdx, docs/api_reference/api_reference/query_engine/index.md

API Components and Reference Notes

The API reference source for query engines contains the directive ::: llama_index.core.base.base_query_engine, which means the rendered documentation is generated from the core base query engine object rather than manually duplicated in Markdown. For readers, the important implication is that the base query engine is the reference entry point for the shared query interface. For maintainers, it means API-reference accuracy depends on the Python object and its docstrings, while the Markdown page remains a stable navigation anchor under the query engine API family.

Sources: docs/api_reference/api_reference/query_engine/index.md

The FLARE schema is a small but useful window into advanced query-engine internals. QueryTask is a dataclass with three fields: query_str, start_idx, and end_idx. The name and fields indicate a task-oriented representation of a query string plus start and end indexes, which is consistent with query engines that need to decompose, localize, or track parts of generated text during an iterative answer process. Application developers usually interact with higher-level query engines, but extension authors should notice that specialized engines may introduce precise internal schemas for subquery planning and span bookkeeping.

Sources: llama-index-core/llama_index/core/query_engine/flare/schema.py

Composition and Deployment Guidance

When deploying a query engine, keep the public boundary narrow. Application handlers should receive a question, call the query engine, and serialize or render the response. Index construction, model selection, ingestion, and retrieval tuning should be configured before or around that boundary. This separation makes it easier to change storage backends, retrieval parameters, response synthesis strategies, or streaming behavior without rewriting every endpoint. The official guide reinforces this separation by presenting query engines as deployment interfaces and linking from the concept page to deeper usage-pattern, module, and supporting-module documentation.

Sources: docs/src/content/docs/framework/module_guides/deploying/query_engine/index.mdx

Composition becomes important once a single index is no longer enough. Because the guide explicitly says multiple query engines can be composed, a production system can expose one application-level question endpoint while delegating to specialized engines underneath. One engine might query product documentation, another might query support tickets, and another might wrap a graph-backed store. The composition layer can route, merge, or compare results while each child query engine keeps its own retrieval and synthesis choices. This pattern keeps domain boundaries clear and makes testing easier because each engine can be exercised with representative questions before being combined.

Sources: docs/src/content/docs/framework/module_guides/deploying/query_engine/index.mdx

Implementation Details and Next Steps

A useful query-engine implementation should be evaluated from both the caller’s perspective and the pipeline owner’s perspective. Callers care about a stable query operation, response shape, latency, and optional streaming behavior. Pipeline owners care about how the engine was produced from an index, which retriever it uses, whether additional modules filter or transform retrieved context, and whether advanced schemas such as FLARE query tasks are involved. Keeping those concerns separate helps teams expose a simple application API while still improving retrieval quality and response generation behind the scenes.

Sources: docs/src/content/docs/framework/module_guides/deploying/query_engine/index.mdx, llama-index-core/llama_index/core/query_engine/flare/schema.py

For a first implementation, build or load an index, create index.as_query_engine(), and run a known question with an expected answer. Then test streaming=True if the user interface benefits from incremental output. After the baseline works, decide whether the next improvement belongs in retrieval, response synthesis, node postprocessing, or composition with another query engine. Read the related pages on indexes, retrievers, response synthesis, chat engines, and streaming to choose the correct abstraction before adding custom orchestration.