0
# Query Engines
1

2
High-level interfaces for question-answering over indexed data. Query engines combine retrieval, processing, and response synthesis to provide comprehensive answers to user queries with support for various reasoning patterns and data sources.
3

4
## Capabilities
5

6
### Base Query Engine Interface
7

8
Foundation interface for all query engines, providing the core query method and response handling.
9

10
```python { .api }
11
class BaseQueryEngine:
12
    """
13
    Base interface for query engines.
14
    
15
    Parameters:
16
    - callback_manager: Optional[CallbackManager], callback management
17
    """
18
    def __init__(self, callback_manager: Optional[CallbackManager] = None): ...
19
    
20
    def query(self, str_or_query_bundle: Union[str, QueryBundle]) -> RESPONSE_TYPE:
21
        """
22
        Query the engine with a string or QueryBundle.
23
        
24
        Parameters:
25
        - str_or_query_bundle: Union[str, QueryBundle], query input
26
        
27
        Returns:
28
        RESPONSE_TYPE: Query response
29
        """
30
        
31
    async def aquery(self, str_or_query_bundle: Union[str, QueryBundle]) -> RESPONSE_TYPE:
32
        """Async version of query method."""
33
```
34

35
### Retriever Query Engine
36

37
Standard query engine that combines a retriever for finding relevant content with a response synthesizer for generating answers.
38

39
```python { .api }
40
class RetrieverQueryEngine(BaseQueryEngine):
41
    """
42
    Query engine using retriever + response synthesizer pattern.
43
    
44
    Parameters:
45
    - retriever: BaseRetriever, retriever for finding relevant content
46
    - response_synthesizer: Optional[BaseSynthesizer], synthesizer for generating responses
47
    - node_postprocessors: Optional[List[BaseNodePostprocessor]], postprocessors for retrieved nodes
48
    - callback_manager: Optional[CallbackManager], callback management
49
    """
50
    def __init__(
51
        self,
52
        retriever: BaseRetriever,
53
        response_synthesizer: Optional[BaseSynthesizer] = None,
54
        node_postprocessors: Optional[List[BaseNodePostprocessor]] = None,
55
        callback_manager: Optional[CallbackManager] = None
56
    ): ...
57
    
58
    @classmethod
59
    def from_args(
60
        cls,
61
        retriever: BaseRetriever,
62
        response_mode: str = "compact",
63
        text_qa_template: Optional[BasePromptTemplate] = None,
64
        **kwargs
65
    ) -> "RetrieverQueryEngine":
66
        """Create query engine with specified configuration."""
67
```
68

69
### Custom Query Engine
70

71
Base class for implementing custom query engine logic with full control over the query processing pipeline.
72

73
```python { .api }
74
class CustomQueryEngine(BaseQueryEngine):
75
    """
76
    Base class for custom query engine implementations.
77
    
78
    Parameters:
79
    - query_fn: Callable, function that processes queries
80
    - callback_manager: Optional[CallbackManager], callback management
81
    """
82
    def __init__(
83
        self,
84
        query_fn: Callable[[Union[str, QueryBundle]], RESPONSE_TYPE],
85
        callback_manager: Optional[CallbackManager] = None
86
    ): ...
87
```
88

89
### Router Query Engine
90

91
Query engine that routes queries to different sub-engines based on query content or metadata, enabling specialized handling for different query types.
92

93
```python { .api }
94
class RouterQueryEngine(BaseQueryEngine):
95
    """
96
    Routes queries to different query engines based on selection criteria.
97
    
98
    Parameters:
99
    - selector: BaseSelector, selector for choosing query engine
100
    - query_engine_tools: Sequence[QueryEngineTool], available query engines
101
    - verbose: bool, whether to output selection reasoning
102
    - callback_manager: Optional[CallbackManager], callback management
103
    """
104
    def __init__(
105
        self,
106
        selector: BaseSelector,
107
        query_engine_tools: Sequence[QueryEngineTool],
108
        verbose: bool = True,
109
        callback_manager: Optional[CallbackManager] = None
110
    ): ...
111
    
112
    @classmethod
113
    def from_defaults(
114
        cls,
115
        query_engine_tools: Sequence[QueryEngineTool],
116
        selector: Optional[BaseSelector] = None,
117
        selector_type: str = "single",
118
        **kwargs
119
    ) -> "RouterQueryEngine":
120
        """Create router with default selector."""
121
```
122

123
### Sub Question Query Engine
124

125
Query engine that decomposes complex queries into sub-questions, answers each independently, and synthesizes a final comprehensive response.
126

127
```python { .api }
128
class SubQuestionQueryEngine(BaseQueryEngine):
129
    """
130
    Decomposes complex queries into sub-questions for comprehensive answers.
131
    
132
    Parameters:
133
    - question_gen: SubQuestionGenerator, generator for creating sub-questions
134
    - query_engine_tools: Sequence[QueryEngineTool], tools for answering sub-questions
135
    - response_synthesizer: Optional[BaseSynthesizer], synthesizer for final response
136
    - verbose: bool, whether to show sub-question processing
137
    - callback_manager: Optional[CallbackManager], callback management
138
    """
139
    def __init__(
140
        self,
141
        question_gen: SubQuestionGenerator,
142
        query_engine_tools: Sequence[QueryEngineTool],
143
        response_synthesizer: Optional[BaseSynthesizer] = None,
144
        verbose: bool = True,
145
        callback_manager: Optional[CallbackManager] = None
146
    ): ...
147
    
148
    @classmethod
149
    def from_defaults(
150
        cls,
151
        query_engine_tools: Sequence[QueryEngineTool],
152
        question_gen: Optional[SubQuestionGenerator] = None,
153
        **kwargs
154
    ) -> "SubQuestionQueryEngine":
155
        """Create sub-question query engine with defaults."""
156

157
class SubQuestionAnswerPair:
158
    """Container for sub-question and its answer."""
159
    def __init__(self, sub_q: SubQuestion, answer: str): ...
160
```
161

162
### Multi-Step Query Engine
163

164
Query engine implementing multi-step reasoning, where each step builds upon previous results to handle complex analytical queries.
165

166
```python { .api }
167
class MultiStepQueryEngine(BaseQueryEngine):
168
    """
169
    Implements multi-step reasoning for complex queries.
170
    
171
    Parameters:
172
    - query_engine: BaseQueryEngine, base query engine for individual steps
173
    - query_transform: BaseQueryTransform, transformation for step queries
174
    - index_summary: str, summary of indexed content
175
    - num_steps: Optional[int], maximum number of reasoning steps
176
    - callback_manager: Optional[CallbackManager], callback management
177
    """
178
    def __init__(
179
        self,
180
        query_engine: BaseQueryEngine,
181
        query_transform: BaseQueryTransform,
182
        index_summary: str,
183
        num_steps: Optional[int] = None,
184
        callback_manager: Optional[CallbackManager] = None
185
    ): ...
186
```
187

188
### Transform Query Engine
189

190
Query engine that applies transformations to queries before processing, enabling query enhancement, reformulation, or filtering.
191

192
```python { .api }
193
class TransformQueryEngine(BaseQueryEngine):
194
    """
195
    Applies transformations to queries before processing.
196
    
197
    Parameters:
198
    - query_engine: BaseQueryEngine, underlying query engine
199
    - query_transform: BaseQueryTransform, transformation to apply
200
    - callback_manager: Optional[CallbackManager], callback management
201
    """
202
    def __init__(
203
        self,
204
        query_engine: BaseQueryEngine,
205
        query_transform: BaseQueryTransform,
206
        callback_manager: Optional[CallbackManager] = None
207
    ): ...
208
```
209

210
### Citation Query Engine
211

212
Query engine that provides detailed citations and source attribution for generated responses, enabling transparency and verification.
213

214
```python { .api }
215
class CitationQueryEngine(BaseQueryEngine):
216
    """
217
    Query engine that provides citations for generated responses.
218
    
219
    Parameters:
220
    - retriever: BaseRetriever, retriever for finding relevant content
221
    - response_synthesizer: Optional[BaseSynthesizer], synthesizer with citation support
222
    - citation_chunk_size: int, size of citation chunks
223
    - citation_chunk_overlap: int, overlap between citation chunks
224
    - callback_manager: Optional[CallbackManager], callback management
225
    """
226
    def __init__(
227
        self,
228
        retriever: BaseRetriever,
229
        response_synthesizer: Optional[BaseSynthesizer] = None,
230
        citation_chunk_size: int = 512,
231
        citation_chunk_overlap: int = 20,
232
        callback_manager: Optional[CallbackManager] = None
233
    ): ...
234
```
235

236
### Retry Query Engines
237

238
Query engines with built-in retry mechanisms for handling failures, source validation, and guideline adherence.
239

240
```python { .api }
241
class RetryQueryEngine(BaseQueryEngine):
242
    """
243
    Query engine with retry logic for handling failures.
244
    
245
    Parameters:
246
    - query_engine: BaseQueryEngine, underlying query engine
247
    - evaluator: BaseEvaluator, evaluator for response quality
248
    - max_retries: int, maximum number of retry attempts
249
    - callback_manager: Optional[CallbackManager], callback management
250
    """
251
    def __init__(
252
        self,
253
        query_engine: BaseQueryEngine,
254
        evaluator: BaseEvaluator,
255
        max_retries: int = 3,
256
        callback_manager: Optional[CallbackManager] = None
257
    ): ...
258

259
class RetrySourceQueryEngine(BaseQueryEngine):
260
    """Query engine with retry based on source validation."""
261
    def __init__(
262
        self,
263
        query_engine: BaseQueryEngine,
264
        evaluator: BaseEvaluator,
265
        max_retries: int = 3,
266
        callback_manager: Optional[CallbackManager] = None
267
    ): ...
268

269
class RetryGuidelineQueryEngine(BaseQueryEngine):
270
    """Query engine with retry based on guideline adherence."""
271
    def __init__(
272
        self,
273
        query_engine: BaseQueryEngine,
274
        guideline_evaluator: GuidelineEvaluator,
275
        max_retries: int = 3,
276
        callback_manager: Optional[CallbackManager] = None
277
    ): ...
278
```
279

280
### SQL Query Engines
281

282
Specialized query engines for natural language querying of SQL databases and structured data.
283

284
```python { .api }
285
class NLSQLTableQueryEngine(BaseQueryEngine):
286
    """
287
    Natural language to SQL query engine for database tables.
288
    
289
    Parameters:
290
    - sql_database: SQLDatabase, database connection
291
    - tables: Optional[List[str]], specific tables to query
292
    - context_query_kwargs: Optional[dict], context retrieval configuration
293
    - synthesize_response: bool, whether to synthesize natural language response
294
    - callback_manager: Optional[CallbackManager], callback management
295
    """
296
    def __init__(
297
        self,
298
        sql_database: SQLDatabase,
299
        tables: Optional[List[str]] = None,
300
        context_query_kwargs: Optional[dict] = None,
301
        synthesize_response: bool = True,
302
        callback_manager: Optional[CallbackManager] = None,
303
        **kwargs
304
    ): ...
305

306
class SQLTableRetrieverQueryEngine(BaseQueryEngine):
307
    """SQL query engine with retriever for table selection."""
308
    def __init__(
309
        self,
310
        sql_database: SQLDatabase,
311
        table_retriever: ObjectRetriever,
312
        context_query_kwargs: Optional[dict] = None,
313
        synthesize_response: bool = True,
314
        callback_manager: Optional[CallbackManager] = None
315
    ): ...
316

317
class PGVectorSQLQueryEngine(BaseQueryEngine):
318
    """PostgreSQL vector query engine for hybrid search."""
319
    def __init__(
320
        self,
321
        sql_database: SQLDatabase,
322
        query_str: str,
323
        embed_model: Optional[BaseEmbedding] = None,
324
        callback_manager: Optional[CallbackManager] = None
325
    ): ...
326

327
class SQLJoinQueryEngine(BaseQueryEngine):
328
    """SQL query engine supporting joins across multiple tables."""
329
    def __init__(
330
        self,
331
        sql_database: SQLDatabase,
332
        tables: List[str],
333
        callback_manager: Optional[CallbackManager] = None
334
    ): ...
335

336
class SQLAutoVectorQueryEngine(BaseQueryEngine):
337
    """Automatic SQL vector query engine with intelligent query planning."""
338
    def __init__(
339
        self,
340
        sql_database: SQLDatabase,
341
        vector_store_info: VectorStoreInfo,
342
        callback_manager: Optional[CallbackManager] = None
343
    ): ...
344
```
345

346
### Pandas Query Engine
347

348
Query engine for natural language querying of pandas DataFrames and structured tabular data.
349

350
```python { .api }
351
class PandasQueryEngine(BaseQueryEngine):
352
    """
353
    Natural language query engine for pandas DataFrames.
354
    
355
    Parameters:
356
    - df: pd.DataFrame, DataFrame to query
357
    - instruction_str: Optional[str], custom instructions for querying
358
    - output_processor: Optional[Callable], processor for query results
359
    - pandas_config: Optional[dict], pandas configuration options
360
    - head: int, number of DataFrame rows to show in context
361
    - callback_manager: Optional[CallbackManager], callback management
362
    """
363
    def __init__(
364
        self,
365
        df: "pd.DataFrame",
366
        instruction_str: Optional[str] = None,
367
        output_processor: Optional[Callable] = None,
368
        pandas_config: Optional[dict] = None,
369
        head: int = 5,
370
        callback_manager: Optional[CallbackManager] = None,
371
        **kwargs
372
    ): ...
373
```
374

375
### Specialized Query Engines
376

377
Additional query engines for specific use cases and integrations.
378

379
```python { .api }
380
class JSONalyzeQueryEngine(BaseQueryEngine):
381
    """Query engine for analyzing JSON data structures."""
382
    def __init__(
383
        self,
384
        json_value: Union[str, dict, List[dict]],
385
        callback_manager: Optional[CallbackManager] = None,
386
        **kwargs
387
    ): ...
388

389
class KnowledgeGraphQueryEngine(BaseQueryEngine):
390
    """Query engine for knowledge graph traversal and reasoning."""
391
    def __init__(
392
        self,
393
        storage_context: StorageContext,
394
        refresh_schema: bool = False,
395
        verbose: bool = True,
396
        callback_manager: Optional[CallbackManager] = None,
397
        **kwargs
398
    ): ...
399

400
class SimpleMultiModalQueryEngine(BaseQueryEngine):
401
    """Simple multi-modal query engine for text and image content."""
402
    def __init__(
403
        self,
404
        retriever: BaseRetriever,
405
        multi_modal_llm: Optional[MultiModalLLM] = None,
406
        text_qa_template: Optional[BasePromptTemplate] = None,
407
        callback_manager: Optional[CallbackManager] = None
408
    ): ...
409

410
class CogniswitchQueryEngine(BaseQueryEngine):
411
    """Query engine integration with Cogniswitch platform."""
412
    def __init__(
413
        self,
414
        cs_token: str,
415
        OAI_token: str,
416
        apiKey: str,
417
        callback_manager: Optional[CallbackManager] = None
418
    ): ...
419

420
class ComposableGraphQueryEngine(BaseQueryEngine):
421
    """Query engine for composable graph structures."""
422
    def __init__(
423
        self,
424
        graph: ComposableGraph,
425
        custom_query_engines: Optional[Dict[str, BaseQueryEngine]] = None,
426
        recursive: bool = True,
427
        callback_manager: Optional[CallbackManager] = None
428
    ): ...
429
```
430

431
### FLARE Query Engine
432

433
Implementation of the FLARE (Forward-Looking Active REtrieval) pattern for iterative query processing with active retrieval.
434

435
```python { .api }
436
class FLAREInstructQueryEngine(BaseQueryEngine):
437
    """
438
    FLARE (Forward-Looking Active REtrieval) query engine.
439
    
440
    Parameters:
441
    - query_engine: BaseQueryEngine, base query engine for retrieval
442
    - lookahead_answer_inserter: BaseLookaheadAnswerInserter, answer insertion logic
443
    - callback_manager: Optional[CallbackManager], callback management
444
    """
445
    def __init__(
446
        self,
447
        query_engine: BaseQueryEngine,
448
        lookahead_answer_inserter: BaseLookaheadAnswerInserter,
449
        callback_manager: Optional[CallbackManager] = None
450
    ): ...
451
```
452

453
## Response Synthesis Functions
454

455
Factory function for creating response synthesizers used by query engines.
456

457
```python { .api }
458
def get_response_synthesizer(
459
    response_mode: str = "compact",
460
    text_qa_template: Optional[BasePromptTemplate] = None,
461
    refine_template: Optional[BasePromptTemplate] = None,
462
    summary_template: Optional[BasePromptTemplate] = None,
463
    simple_template: Optional[BasePromptTemplate] = None,
464
    use_async: bool = False,
465
    streaming: bool = False,
466
    structured_answer_filtering: bool = False,
467
    **kwargs
468
) -> BaseSynthesizer:
469
    """
470
    Factory function for creating response synthesizers.
471
    
472
    Parameters:
473
    - response_mode: str, synthesis mode ("compact", "refine", "tree_summarize", etc.)
474
    - text_qa_template: Optional[BasePromptTemplate], template for Q&A
475
    - refine_template: Optional[BasePromptTemplate], template for refinement
476
    - summary_template: Optional[BasePromptTemplate], template for summarization
477
    - simple_template: Optional[BasePromptTemplate], template for simple responses
478
    - use_async: bool, whether to use async processing
479
    - streaming: bool, whether to enable streaming responses
480
    - structured_answer_filtering: bool, whether to filter structured answers
481
    
482
    Returns:
483
    BaseSynthesizer: Configured response synthesizer
484
    """
485
```
486

487
## Usage Examples
488

489
### Basic Query Engine Usage
490

491
```python
492
from llama_index.core import VectorStoreIndex, Document
493
from llama_index.core.query_engine import RetrieverQueryEngine
494

495
# Create index and documents
496
documents = [
497
    Document(text="Machine learning is a subset of artificial intelligence."),
498
    Document(text="Deep learning uses neural networks with multiple layers."),
499
    Document(text="Natural language processing enables computers to understand text.")
500
]
501
index = VectorStoreIndex.from_documents(documents)
502

503
# Create and use query engine
504
query_engine = index.as_query_engine()
505
response = query_engine.query("What is machine learning?")
506
print(response.response)
507
print(f"Sources: {len(response.source_nodes)}")
508
```
509

510
### Router Query Engine for Specialized Handling
511

512
```python
513
from llama_index.core.query_engine import RouterQueryEngine
514
from llama_index.core.tools import QueryEngineTool
515

516
# Create specialized query engines
517
vector_engine = vector_index.as_query_engine()
518
keyword_engine = keyword_index.as_query_engine()
519

520
# Define query engine tools
521
query_engine_tools = [
522
    QueryEngineTool.from_defaults(
523
        query_engine=vector_engine,
524
        description="Useful for semantic similarity queries"
525
    ),
526
    QueryEngineTool.from_defaults(
527
        query_engine=keyword_engine,
528
        description="Useful for exact keyword matching"
529
    )
530
]
531

532
# Create router query engine
533
router_engine = RouterQueryEngine.from_defaults(
534
    query_engine_tools=query_engine_tools,
535
    verbose=True
536
)
537

538
response = router_engine.query("Find documents about machine learning")
539
```
540

541
### Sub-Question Decomposition
542

543
```python
544
from llama_index.core.query_engine import SubQuestionQueryEngine
545

546
# Create sub-question query engine
547
sub_question_engine = SubQuestionQueryEngine.from_defaults(
548
    query_engine_tools=query_engine_tools,
549
    verbose=True
550
)
551

552
# Query with complex question
553
response = sub_question_engine.query(
554
    "Compare machine learning and deep learning approaches, "
555
    "and explain their applications in natural language processing"
556
)
557
```
558

559
### SQL Database Querying
560

561
```python
562
from llama_index.core.query_engine import NLSQLTableQueryEngine
563
from llama_index.core import SQLDatabase
564

565
# Connect to database
566
sql_database = SQLDatabase.from_uri("sqlite:///example.db")
567

568
# Create SQL query engine
569
sql_engine = NLSQLTableQueryEngine(
570
    sql_database=sql_database,
571
    tables=["customers", "orders", "products"],
572
    synthesize_response=True
573
)
574

575
# Query in natural language
576
response = sql_engine.query("How many orders were placed last month?")
577
```
578

579
### Custom Query Engine Implementation
580

581
```python
582
from llama_index.core.query_engine import CustomQueryEngine
583

584
def custom_query_fn(query_bundle):
585
    """Custom query processing logic."""
586
    query_str = query_bundle.query_str
587
    # Implement custom logic here
588
    return f"Custom response for: {query_str}"
589

590
# Create custom query engine
591
custom_engine = CustomQueryEngine(query_fn=custom_query_fn)
592
response = custom_engine.query("Custom query")
593
```
594

595
## Types & Enums
596

597
```python { .api }
598
RESPONSE_TYPE = Union[str, Response, StreamingResponse]
599

600
class ResponseMode(str, Enum):
601
    """Response synthesis modes."""
602
    REFINE = "refine"
603
    COMPACT = "compact"
604
    TREE_SUMMARIZE = "tree_summarize"
605
    SIMPLE_SUMMARIZE = "simple_summarize"
606
    GENERATION = "generation"
607
    ACCUMULATE = "accumulate"
608
    COMPACT_ACCUMULATE = "compact_accumulate"
609
```