Implementation:Run llama Llama index BaseQueryEngine

Knowledge Sources	Run_llama_Llama_index
Domains	LLM Framework, Query Engine
Last Updated	2026-02-11 19:00 GMT

Overview

BaseQueryEngine is the abstract base class for all query engines in LlamaIndex, defining the interface for synchronous and asynchronous query execution with built-in instrumentation, callback tracing, and event dispatching.

Description

The BaseQueryEngine class inherits from PromptMixin (for prompt management) and DispatcherSpanMixin (for instrumentation spans). It provides the core query execution framework:

Constructor:

• Accepts an optional CallbackManager for tracing; defaults to an empty manager if none is provided.

Public methods:

• query(str_or_query_bundle) -- Synchronous entry point. Converts a string to a QueryBundle if needed, fires QueryStartEvent and QueryEndEvent instrumentation events, wraps execution in a callback trace, then delegates to the abstract _query method.
• aquery(str_or_query_bundle) -- Asynchronous counterpart of query, following the same pattern but awaiting _aquery.

Optional override methods:

• retrieve(query_bundle) -- Raises NotImplementedError by default. Can be overridden by subclasses that support a separate retrieval step.
• synthesize(query_bundle, nodes, ...) -- Raises NotImplementedError by default. Can be overridden by subclasses that support a separate synthesis step.
• asynthesize(query_bundle, nodes, ...) -- Async variant of synthesize, also raises NotImplementedError by default.

Abstract methods (must be implemented by subclasses):

• _query(query_bundle) -- The core synchronous query logic.
• _aquery(query_bundle) -- The core asynchronous query logic.

The PromptMixin integration provides default no-op implementations for _get_prompts and _update_prompts, which subclasses can override to expose configurable prompts.

Usage

Subclass BaseQueryEngine to create custom query engines. All standard LlamaIndex query engines (e.g., RetrieverQueryEngine, SubQuestionQueryEngine) extend this base class. Use the public query() or aquery() methods as the primary interface.

Code Reference

Source Location

• Repository: Run_llama_Llama_index
• File: llama-index-core/llama_index/core/base/base_query_engine.py
• Lines: 1-93

Signature

class BaseQueryEngine(PromptMixin, DispatcherSpanMixin):
    """Base query engine."""

    def __init__(
        self,
        callback_manager: Optional[CallbackManager],
    ) -> None: ...

    def query(self, str_or_query_bundle: QueryType) -> RESPONSE_TYPE: ...

    async def aquery(self, str_or_query_bundle: QueryType) -> RESPONSE_TYPE: ...

    def retrieve(self, query_bundle: QueryBundle) -> List[NodeWithScore]: ...

    def synthesize(
        self,
        query_bundle: QueryBundle,
        nodes: List[NodeWithScore],
        additional_source_nodes: Optional[Sequence[NodeWithScore]] = None,
    ) -> RESPONSE_TYPE: ...

    async def asynthesize(
        self,
        query_bundle: QueryBundle,
        nodes: List[NodeWithScore],
        additional_source_nodes: Optional[Sequence[NodeWithScore]] = None,
    ) -> RESPONSE_TYPE: ...

    @abstractmethod
    def _query(self, query_bundle: QueryBundle) -> RESPONSE_TYPE: ...

    @abstractmethod
    async def _aquery(self, query_bundle: QueryBundle) -> RESPONSE_TYPE: ...

Import

from llama_index.core.base.base_query_engine import BaseQueryEngine

I/O Contract

Inputs

Name	Type	Required	Description
callback_manager	Optional[CallbackManager]	No	Callback manager for tracing and instrumentation. Defaults to an empty CallbackManager.
str_or_query_bundle	QueryType (str or QueryBundle)	Yes	The query to execute. Strings are automatically wrapped in a QueryBundle.

Outputs

Name	Type	Description
return (query/aquery)	RESPONSE_TYPE	The query response, typically a Response or StreamingResponse object.
return (retrieve)	List[NodeWithScore]	Retrieved nodes (only if subclass supports it; raises NotImplementedError by default).

Usage Examples

Basic Usage

from llama_index.core.base.base_query_engine import BaseQueryEngine
from llama_index.core.base.response.schema import RESPONSE_TYPE, Response
from llama_index.core.schema import QueryBundle

class SimpleQueryEngine(BaseQueryEngine):
    def __init__(self):
        super().__init__(callback_manager=None)

    def _query(self, query_bundle: QueryBundle) -> RESPONSE_TYPE:
        # Custom query logic
        return Response(response="Answer to: " + query_bundle.query_str)

    async def _aquery(self, query_bundle: QueryBundle) -> RESPONSE_TYPE:
        return self._query(query_bundle)

# Usage
engine = SimpleQueryEngine()
response = engine.query("What is LlamaIndex?")
print(response)

Related Pages

• Environment:Run_llama_Llama_index_Python_LlamaIndex_Core